Tutorial - Sign Code in GitHub Workflows with GitHub Actions and SignServer

The SignServer Signing Action can be added to any GitHub workflow to add signing to your pipelines.

This tutorial will go through an example of a project creating a jar from a simple HelloWorld project and using the signing action to sign the outputted jar for upload to a chosen location.

The tutorial covers these steps:

Set up SignServer to receive a signing request from a GitHub Action.
Set up a GitHub repository and secrets needed to run the signing action.
Use the SignServer Signing action in a workflow.

Prerequisites

For this tutorial, SignServer Community Docker container version 6.3 was used.

Before you begin, you need:

A running SignServer instance - Click to learn more

If you don’t already have SignServer installed, here are some options for you:

Download SignServer - Free and open-source SignServer Community version
- There are tutorials to help you, for example, see this one on how to run the SignServer Docker container: Quick Start Guide - Start SignServer Container with Client Certificate Authenticated Access.
Try on AWS - Free 30-day trial SignServer Cloud on AWS
Try on Azure - Free 30-day trial SignServer Cloud on Azure

An account and repository on GitHub for your workflow and use of the signing action.

Step 1 - Set up SignServer

For this tutorial, you need a running SignServer instance accessible from the GitHub-hosted runners. Hosting the action yourself could require a different setup.

In this tutorial, a SignServer container is used on a cloud instance and the worker requires client certificate authentication for signing requests.

Add a CryptoTokenP12 in SignServer

Follow the steps below to add the CryptoTokenP12 worker using the sample configuration file keystore-crypto.properties as a template.

To add the CryptoTokenP12 worker, follow the steps below and use the template keystore-crypto.properties:

Go to the SignServer Admin Web Workers page and click Add to add a new worker.
On the Add Worker / Load Configuration page, choose the method From Template.
In the Load From Template list menu, select keystore-crypto.properties and click Next.
Click Apply.
Select the worker in the list and confirm that the Worker status is Active and without errors listed

Add a Jarchive Signer in SignServer

Follow the steps below to add the Jarchive signer with ClientCert authentication using the sample configuration file jarchive_signer.properties as a template.

To add the Jarchive signer, follow the steps below and use the template jarchive_signer.properties:

Go to the SignServer Admin Web Workers page and click Add to add a new worker.
On the Add Worker / Load Configuration page, choose the method From Template.
In the Load From Template list menu, select jarchive_signer.properties and click Next.
Click Apply
Select the worker in the list and confirm that the Worker status is Active and without errors listed
For more information on how to set up client certificate authorization, see Configure Client Certificate Authentication and Authorization.

Step 2 - Set up a GitHub Workflow

Set up a GitHub repository

Choose which repository you want to run your action in, either a new or existing one. If you need help to set up a new project with a jar for signing and a workflow, here are some hints:

Provided sample files can be used for a simple HelloWorld project
HelloWorld sample code for creation of a Jar to be signed: HelloWorld.zip
Sample workflow: demo-signserver.yml

Set up secrets

For this tutorial, a signer using client certificate as authentication is used. Therefore, the Action will need to have the ClientCert as well as the password. Both of these are set as secrets in GitHub, as well as the SignServer URL for the running SignServer instance.

Secrets are created on GitHub under Settings > Secrets and variables > Actions.

For this sample case, three secrets are needed:

SignServer URL endpoint: SIGNSERVER_URL
Client Cert: SIGNSERVER_CLIENT_CERT
Client Cert Credentials: SIGNSERVER_CLIENT_CRED

These can be used in your workflow through ${{ secrets.SIGNSERVER_URL }} for example.

Set up a workflow

For this tutorial, a sample yml file has been provided which can be used – or you can create you own. The file needs to be placed under the .github/worflows folder with .yml or .yaml for GitHub to recognize it as a workflow.

If the sample .yml file is used, the HelloWorld folder provided needs to be added to the repository home.

Steps in the sample file:

Create HelloWorld.jar
Upload Jar to artifacts
Download Jar for signing
Download Client certificate from secrets
Sign Jar using SignServer action and upload to artifacts
Verify signed Jar

Step 3 - Run GitHub Action

If sample files are used, you should now be able to go to Actions and run your workflow. The created jar as well as the signed jar will be uploaded to artifact for you to download once the workflow is done.

A workflow can be triggered manually or at certain events. In this tutorial, the workflow is triggered manually. To set up other triggers for when to run workflow using the signing action, refer to the GitHub Docs on Choosing when your workflow runs.

Next steps

In this tutorial, you learned how to set up and run the SignServer Signing GitHub Action.

Here are some next steps we recommend:

Try out post-quantum signing, see Tutorial - SignServer Post-Quantum signing.

If you are interested in SignServer Enterprise, read more on Keyfactor SignServer Enterprise.

If you are interested in SignServer Community, check out SignServer Community vs Enterprise or read more on signserver.org.
If you are a SignServer Enterprise customer and need support, visit the Keyfactor Support Portal.
Discuss with the SignServer Community on GitHub Discussions.