Binary signing using GitHub Actions (Recommended)

ヒント

As a DigiCert® KeyLocker user, you can enhance your code signing workflow using DigiCert® Software Trust Manager plugins.

Also known as Code signing with DigiCert Software Trust Manager, DigiCert Binary Signing is a GitHub Actions that enables teams to integrate code signing into their CI/CD workflows for multiple platforms using Software Trust.

This action automates the setup and invocation of the signing tool, manages certificates and key pairs, and enforces security best practices, such as multi-factor authentication and audit logging.

The action is especially valuable for organizations that need to ensure the integrity and authenticity of binaries, comply with signing-related security policies, and streamline high-volume release workflows.

To view the GitHub Marketplace entry and learn how to get started, see DigiCert Binary Signing.

注記

Binary signing using GitHub Actions replaces the GitHub Action Code signing with Software Trust Manager.

This new GitHub Action includes all existing code signing capabilities as the legacy Code signing with Software Trust Manager, along with additional enhancements that simplify and scale your signing workflows.

What's new?

Among other time-saving features, the action supports simple signing:

Simple signing allows you to sign without third-party signing tools (SignTool, Jarsigner, etc.) or intermediate libraries (KSP, PKCS#11, etc.).
To more about simple signing, see 署名を管理する.

Before you begin

As a best practice, consider enabling simple signing mode for your new implementations.

Simple signing mode:

Simplifies your workflow
There is no need for third-party signing tools (SignTool, Jarsigner, etc.) or intermediate libraries (smksp, smpkcs11, etc.).
Offers cross-platform support
This mode works seamlessly across Windows, Linux, and macOS.
Provides a unified signing experience
There is a single, consistent approach for all supported file types.
Is future ready
As we deprecate legacy signing methods, this mode is aligned with our strategic direction.
Offers better performance
Simple signing mode is faster than traditional signing because there is no need for intermediate libraries, third-party tool integrations, or unnecessary API calls.
Supports bulk signing
You can enable bulk-sign-mode: true to sign multiple files in a single batch operation, significantly reducing network round trips and improving throughput for large-scale signing. (By default, this feature is disabled and is only available for Software Trust users. To enable this feature, contact your DigiCert account manager.)
ヒント
By default, the simple signing mode is disabled to ensure seamless migration from our legacy GitHub Actions without breaking existing workflows. However, we encourage all new users to adopt simple signing and all existing users to migrate when possible.

Migrate to DigiCert Binary Signing

Use this section if you currently use the Code signing with Software Trust Manager GitHub Action. This procedure walks you through updating your existing workflow to use Binary signing using GitHub Actions.

To migrate, update your workflow by replacing the uses value in your repository.

Before (deprecated)

- name: Setup Software Trust Manager
  id: stm-setup
  uses: digicert/ssm-code-signing@v1.1.1

After (recommended)

- name: Setup Software Trust Manager
  id: stm-setup
  uses: digicert/code-signing-software-trust-action@v1.0.0

注記

No other workflow changes are required.

Get started with DigiCert Binary Signing

Use this section if you are setting up DigiCert Binary signing in GitHub Actions for the first time. This procedure walks you through creating a new workflow and configuring the required credentials and inputs.

Step 1: Add steps to your workflow YAML file

Copy and paste one of the following steps into your GitHub Actions workflow YAML file to obtain the latest stable version of Software Trust.

To learn more about these steps, see action.yml.

For Windows

Select one of the following options:

例 1. Option 1: Software Trust with standard features

steps:
  - name: Setup SM_CLIENT_CERT_FILE from base64 secret data
    run: |
      echo "${{ secrets.SM_CLIENT_CERT_FILE_B64 }}" | base64 --decode > /d/sm_client_cert.p12
      shell: bash
  - name: Setup Software Trust Manager
    uses: digicert/code-signing-software-trust-action@v1
      SM_HOST: ${{ vars.SM_HOST }}
      SM_API_KEY: ${{ secrets.SM_API_KEY }}
      SM_CLIENT_CERT_FILE: D:\\Certificate_pkcs12.p12
      SM_CLIENT_CERT_PASSWORD: ${{ secrets.SM_CLIENT_CERT_PASSWORD }}

例 2. Option 2: Software Trust with simple signing (Recommended)

steps:
  - name: Setup SM_CLIENT_CERT_FILE from base64 secret data
    run: |
      echo "${{ secrets.SM_CLIENT_CERT_FILE_B64 }}" | base64 --decode > /d/sm_client_cert.p12
      shell: bash
  - name: Setup Software Trust Manager
    uses: digicert/code-signing-software-trust-action@v1
    with:
      simple-signing-mode: true
      # If the below 2 parameters are supplied, then smctl executable is invoked to attempt the signing.
      input: <file or directory with list of supported files to sign>
      keypair-alias: <a Software Trust Manager keypair to sign with>
    env:
      SM_HOST: ${{ vars.SM_HOST }}
      SM_API_KEY: ${{ secrets.SM_API_KEY }}
      SM_CLIENT_CERT_FILE: D:\\Certificate_pkcs12.p12
      SM_CLIENT_CERT_PASSWORD: ${{ secrets.SM_CLIENT_CERT_PASSWORD }}

ヒント

By default, the simple signing mode is disabled to ensure seamless migration from our legacy GitHub Actions without breaking existing workflows. However, we encourage all new users to adopt simple signing and all existing users to migrate when possible.

To enable this simple signing, contact your DigiCert account manager

For Ubuntu and macOS

Select one of the following options:

例 3. Option 1: Software Trust with standard features

steps:
  - name: Setup SM_CLIENT_CERT_FILE from base64 secret data
    run: |
      export SM_CLIENT_CERT_FILE=${RUNNER_TEMP_DIR}/sm_client_cert.p12
      echo "${{ secrets.SM_CLIENT_CERT_FILE_B64 }}" | base64 --decode > ${SM_CLIENT_CERT_FILE}
      shell: bash
  - name: Setup Software Trust Manager
    uses: digicert/code-signing-software-trust-action@v1
    env:
      SM_HOST: ${{ vars.SM_HOST }}
      SM_API_KEY: ${{ secrets.SM_API_KEY }}
      SM_CLIENT_CERT_FILE: ${SM_CLIENT_CERT_FILE}
      SM_CLIENT_CERT_PASSWORD: ${{ secrets.SM_CLIENT_CERT_PASSWORD }}

例 4. Option 2: Software Trust with simple signing (Recommended)

steps:
  - name: Setup SM_CLIENT_CERT_FILE from base64 secret data
    run: |
      export SM_CLIENT_CERT_FILE=${RUNNER_TEMP_DIR}/sm_client_cert.p12
      echo "${{ secrets.SM_CLIENT_CERT_FILE_B64 }}" | base64 --decode > ${SM_CLIENT_CERT_FILE}
      shell: bash
  - name: Setup Software Trust Manager
    uses: digicert/code-signing-software-trust-action@v1
    with:
      simple-signing-mode: true
      # If the below 2 parameters are supplied, then smctl executable is invoked to attempt the signing.
      input: <file or directory with list of supported files to sign>
      keypair-alias: <a Software Trust Manager keypair to sign with>
    env:
      SM_HOST: ${{ vars.SM_HOST }}
      SM_API_KEY: ${{ secrets.SM_API_KEY }}
      SM_CLIENT_CERT_FILE: ${SM_CLIENT_CERT_FILE}
      SM_CLIENT_CERT_PASSWORD: ${{ secrets.SM_CLIENT_CERT_PASSWORD }}

ヒント

To enable this simple signing, contact your DigiCert account manager

Step 2: Customize setup (inputs)

Review the following variables that you can use to customize your setup:

Name	Type	Default	Description
`code`	Optional	https://pki-downloads.digicert.com/stm/latest	The URL for the DigiCert® CDN used to download the required Software Trust tools.
`keypair-alias`	Optional	Not applicable	A keypair alias.
`input`	Optional	Not applicable	A file or directory that contains the supported files to sign.
`digest-alg`	Optional	SHA-256	Digest (hash) algorithm.
`fail-fast`	Optional	True	Allows signing of all supported files in a directory, even if some files encounter an error. Only applies if the input is a directory with multiple supported files.
`zero-exit-code-on-failure`	Optional	False	Returns an exit code of 0 even if errors occur during execution. (Not recommended.)
`unsigned`	Optional	False	Signs only unsigned files.
`timestamp`	Optional	True	Enables or disables timestamping on signed files.
`cache-version`	Optional	0.0.0-0	Overrides the default Github tool cache key to prompt GitHub runners to download the next available version. This value is used only for caching purposes and doesn't affect the actual tool version.
`simple-signing-mode`	Optional	False	Installs smctl to enable simplified signing, which eliminates the need for third-party signing tools and provides consistent cross-platform support.
`use-github-caching-service`	Optional	True	Enables GitHub’s built-in caching service. This stores Software Trust tools across workflow runs since default tool caching is not supported on GitHub runners.
`use-binary-sha256-checksum`	Optional	True	Use the SHA-256 checksum file provided on the CDN to handle caching. This ensures that new versions are automatically downloaded when they are available. If this option is not enabled, the system instead relies on cache-version to determine whether a new download is needed. This workflow functions when cache-version is updated and 'use-github-caching-service' is enabled.
`bulk-sign-mode`	Optional	False	Signs multiple files in a single batch operation; only works with simple-signing-mode. This feature must be enabled for your account. Contact your DigiCert account manager to request access.

Step 3: Review required environment variables

Environment variable	Description	Recommendation
`SM_HOST`	The specific environment URL used to connect to Software Trust.	Use GitHub Actions variables
`SM_API_KEY`	An API key generated from your DigiCert® ONE account to use with a service user account.	Use GitHub Actions secrets
`SM_CLIENT_CERT_FILE`	A .p12-format client certificate file generated for the service user from DigiCert® ONE Account Manager.	Use GitHub Actions secrets
`SM_CLIENT_CERT_PASSWORD`	The password for the encrypted .p12 client certificate file.	Use GitHub Actions secrets

注記

Since the client certificate is downloaded as a .p12 file from the DigiCert® ONE Account Manager, as a best practice you should store the file content as a Base64-encoded string in a secret. When you execute, you can decode it into a file using the base64 command (or an equivalent tool).

Review the following example to generate the certificate file from the Base64 secret:

  steps:
 - name: Setup SM_CLIENT_CERT_FILE from base64 secret data
   run: |
     export SM_CLIENT_CERT_FILE=${RUNNER_TEMP_DIR}/sm_client_cert.p12
     echo "${{ secrets.SM_CLIENT_CERT_FILE_B64 }}" | base64 --decode > ${SM_CLIENT_CERT_FILE}
     shell: bash

The base64 command is available by default on Linux and macOS. For Windows runners, verify that the command is supported.

Step 4: Review outputs

The following output is provided by this action:

Name	Description
`PKCS11_CONFIG`	This is the full path to the PKCS#11 configuration file (`pkc11Properties.cfg`). The file is automatically generated when you install Software Trust tools and includes the library path to the PKCS#11 module. Use the value in the output when configuring PKCS#11 for signing operations with third-party tools.

Sample usage:

- name: Setup Software Trust Manager
  id: stm-setup
  uses: digicert/code-signing-software-trust-action@v1
  env:
    SM_HOST: ${{ vars.SM_HOST }}
    SM_API_KEY: ${{ secrets.SM_API_KEY }}
    SM_CLIENT_CERT_FILE: ${{ env.SM_CLIENT_CERT_FILE }}
    SM_CLIENT_CERT_PASSWORD: ${{ secrets.SM_CLIENT_CERT_PASSWORD }}

- name: Use PKCS11 config in subsequent step
  run: |
    echo "PKCS11 config file location: ${{ steps.stm-setup.outputs.PKCS11_CONFIG }}"
    # Use the config file with your signing tool

このセクションの内容: