Why should I create signed releases?

If your software is hosted at GitHub, you may think you don't need to do anything special to release your work for distribution.

A collection of non-sequential, undifferentiated commit hashes is not a good way to refer to known releases of your software. It is a good idea to explicitly create releases each with a clear, meaningful version string. This makes packaging work much easier and also provides an easy to use mechanism for your users to get a specific version of your software.

It is an even better idea to additionally sign your releases using your GnuPG key. This way, your users can verify whether what they received matches the same tarball you have released.

Creating GnuPG-signed releases on GitHub

1. Create a new signed tag in your Git repository:

git tag -s mysoftware-0.4
git push --tags

2. Go to your ?GitHub project and click on the "Releases" link

releases.png

3. Click on "Draft a new release", fill out the tag, title and description field and click on "Publish release"

fillout.png

4. Go back to your "Releases" section and download the tarball mysoftware-0.4.tar.gz automatically generated by ?GitHub. Verify that the tarball contains exactly the same data as the git repository.

5. If you do not have a GnuPG key yet, learn how to create one and make sure it is uploaded to a public keyserver. Be sure to follow the OpenPGP best practices

6. Sign the tarball with your key:

gpg --armor --detach-sign mysoftware-0.4.tar.gz

This should give a file called mysoftware-0.4.tar.gz.asc.

7. Edit your release again and attach the detached signature mysoftware-0.4.tar.gz.asc as binary to the release.

attach.png

You have successfully created a GnuPG-signed release on ?GitHub :)

result.png

Creating GnuPG-signed releases on GitHub - alternative local workflow

The ?GitHub release tarballs can be reproduced bit-by-bit identically. As long as this works the workflow may be simplified, and the comparison of ?GitHub's distributed tarball with your sources gets obsolete.

1. Create a new signed tag in your Git repository (see above).

"mysoftware-0.4" from above example is replaced with "${tag}" from here on.

2. Create a release tarball locally:

git archive --prefix="${tag}/" -o "../${tag}.tar.gz" "${tag}"

3. Have a GnuPG key and make sure it is uploaded to a public keyserver (see above).

4. Sign the locally created tarball with your key:

gpg --armor --detach-sign "../${tag}.tar.gz"

This should give a file in the parent dir called ${tag}.tar.gz.asc.

5. Attach the detached signature ${tag}.tar.gz.asc as binary to the ?GitHub release (see above).

You don't need the previous steps on the ?GitHub website mentioned above. Just go directly to https://github.com/<user>/<project>/releases/edit/${tag} and attach the detached signature.