Skip to content

How to Publish a Signed Succession

This guide explains how to publish a baseprint in a signed digital succession. A digital succession must be signed to be publicly shared for the long-term.

If you only need to create a temporary digital succession for testing, it will be easier to follow the tutorial Publish a Baseprint in a Temporary Digital Succession.

Prerequisites

Before publishing a signed succession, ensure you have the following:

  • A GitHub account
  • Git version 2.34 or newer installed (run git -v to check)
  • OpenSSH 8.8 or newer installed (run ssh -V to check)
  • Hidos installed
  • An SSH signing key
  • Contents of a baseprint

SSH Signing Key Requirement

Git must be configured to use an SSH signing key for signed commits. Additionally, the corresponding public SSH signing key file must be available for use with Hidos. Follow the instructions in Create an SSH Signing Key for Git to meet this requirement.

Baseprint Contents Requirement

There are multiple ways to obtain the contents of a baseprint. One method is described in the tutorial Author a Document Locally, as shown below:

echo Hello World > doc.md
baseprinter doc.md -b=baseprint

Inputs

The following variables are inputs to the steps in this guide:

<username>

Your GitHub account username.

<path-to-baseprint-contents>

The path to a file directory containing the contents of a baseprint. Typically, this directory includes a file named article.xml.

<path_to_public_signing_key>

The filename of the public signing key, usually ending in .pub.

Danger

Make sure you DO NOT use your private signing key when you should use your public signing key.

Steps

1. Create an empty GitHub repository

Do not initialize your new repository with any files. Start with an empty repository.

Create a new repository

Let <reponame> represent the name given to this new repository.

Note

This repository for publication is distinct from the repository, if any, used for the source files used to generate baseprint contents.

2. Create a local bare git repository

git init --bare <reponame>
cd <reponame>

3. Create a signed digital succession

hidos create --keys <path_to_public_signing_key> main

A new Digital Succession Identifier (DSI) will be printed. Take note of this DSI, as it is used to identify the digital succession by other websites and software.

Note

If you do not like the generated DSI, you can regenerate another by performing git branch -D main and repeating the hidos create step.

4. Commit the baseprint contents to the digital succession

hidos commit <path-to-baseprint-contents> main 1

5. Push the digital succession to GitHub

git push <url-to-github-repo>

Replace <url-to-github-repo> with either:

https://github.com/<username>/<reponame>.git

or

git@github.com:<username>/<reponame>.git

Conclusion

You have successfully created a signed digital succession and added a baseprint to it as edition 1. Only individuals with the private signing key can amend this digital succession. Now, software and websites can retrieve this digital succession using the DSI. For example, using the Hidos software, anyone can run the following command to locate the git repository from which this digital succession can be cloned:

hidos find dsi:<your_new_dsi>

More Resources

See the Hidos Reference for more details on hidos commands.