Coming Soon: Binary Signing for GitLab CI/CD

DigiCert Binary Signing for GitLab CI/CD enables organizations to seamlessly integrate secure code signing into GitLab pipelines using DigiCert® Software Trust Manager.

This production-ready CI/CD template supports Linux, macOS, and Windows runners, offering both simplified and traditional signing workflows to align with diverse build and release strategies.

The template automates the setup and execution of DigiCert signing tools, enabling secure keypair-based signing while ensuring private keys remain protected within Software Trust Manager. This approach eliminates direct key exposure in CI environments and strengthens overall signing security.

Supported signing approaches

Simple signing:

Uses the DigiCert SMCTL command-line tool (installed automatically by this template) to sign files directly from the pipeline.
Supports bulk signing of directories.

Traditional signing:

Integrates with third-party signing tools using the following libraries:

JCE
PKCS#11
KSP
CSP

Features:

Cross-platform support: Linux, macOS, and Windows.
Bulk signing support (only for simple signing). Using bulk signing you can sign multiple files at a time.
Secure integration with GitLab Secure Files.
Automatic tool download and caching.
JCE, PKCS#11, KSP, and CSP support for traditional workflows.
Production-ready error handling, logging, and best practices built-in.

Before you begin

Active Software Trust Manager Account.
Active subscription with Software Trust Manager.
API key with signing permissions.
Client certificate (.p12 file) with password.
Set up GitLab Project.
GitLab project with CI/CD enabled.
GitLab runner (SaaS or self-hosted) for your target platform.
Configured required environment variables (see configurations table below).

Variable	Default	Description
`INPUT`	(required)	File or directory to sign
`KEYPAIR_ALIAS`	(required)	DigiCert keypair alias for signing
`DIGEST_ALG`	SHA-256	Digest algorithm (SHA-256, SHA-384, SHA-512)
`TIMESTAMP`	true	Enable RFC 3161 timestamping
`FAIL_FAST`	true	Stop on first error in bulk signing
`BULK_SIGN_MODE`	false	Enable bulk signing for directories
`UNSIGNED_ONLY`	false	Skip already signed files
`ZERO_EXIT_CODE_ON_FAILURE`	false	Return exit code 0 even on signing failure
`CACHE_VERSION`	0.0.0-0	Cache version (change to force re-download)
`DIGICERT_CDN`	https://pki-downloads.digicert.com/stm/latest	DigiCert CDN URL

Get started with DigiCert Binary Signing for GitLab CI/CD

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

Step 1: Upload your certificate

Upload your DigiCert client certificate (.p12 file) to GitLab Secure Files:

Navigate to your GitLab project.
Go to Settings > CI/CD >Secure Files.
Select Upload File and select your .p12 certificate.

Note

The template will automatically detect and use certificates having a .p12 extension.

Step 2: Configure environment variables to authenticate

Add your host, API key, and client certificate password to GitLab variables:

Navigate to your GitLab project.
Go to Settings > CI/CD >Variables .
In the Project variables section, select Add variable.
Add the following variables:

Variable	Descriptions	Required	Protected	Masked
`SM_HOST`	DigiCert API host (e.g., https://clientauth.one.digicert.com)	Yes	Yes	No
`SM_API_KEY`	Your DigiCert API key	Yes	Yes	Yes
`SM_CLIENT_CERT_PASSWORD`	Password for your `.p12`certificate	Yes	Yes	Yes
`SM_CLIENT_CERT_FILE`	Path to certificate (use only if not using Secure Files)	No	Yes	No

Note

Mark sensitive variables as protected and masked for security.

Step 3: Add signing template to GitLab YAML file

Add digicert-signing-template to your .gitlab-ci.yml

include:   - remote: 'https://gitlab.com/<your-namespace>/digicert-signing-template/-/raw/main/templates/digicert-signing.yml'

Step 4: Create your signing job

For simple signing mode you must:

Specify the extend as .simple-signing.
Enter the variables; KEYPAIR_ALIAS and INPUT.

For traditional signing mode you must:

Specify the extend as .traditional-signing.
Use SMCTL or third-party tools signing commands for signing the files with your keypair alias.

Linux/macOS jobs

Linux/macOS templates:

.simple-signing - Simple signing without third-party tools (supports bulk signing).
.traditional-signing - Traditional signing with PKCS#11 setup and more.

Note

To setup a GitLab runner, see https://docs.gitlab.com/runner/install/.

Example 1. Simple Signing - Single File

sign-binary:
  extends: .simple-signing
  stage: sign
  variables:
    INPUT: "build/myapp"
    KEYPAIR_ALIAS: "prod-signing-key"
    DIGEST_ALG: "SHA-256"
    TIMESTAMP: "true"
  artifacts:
    paths:
      - build/myapp
    expire_in: 30 days  # Artifacts kept for 30 days, then auto-deleted

Note

expire_in specifies how long GitLab keeps artifacts before automatic deletion. Use values like 1 hour, 1 day, 30 days, 1 week, or omit for default retention.

Example 2. Simple Signing - Bulk Mode (Multiple files at a time)

For bulk signing, specify the BULK_SIGN_MODE as true.

sign-all-binaries:
  extends: .simple-signing
  stage: sign
  variables:
    INPUT: "dist/"
    KEYPAIR_ALIAS: "prod-signing-key"
    BULK_SIGN_MODE: "true"
    FAIL_FAST: "true"
  artifacts:
    paths:
      - dist/

Example 3. Traditional Signing - 3rd Party tools Integration with Software Trust Manager.

3rd Party tools Integration with Software Trust Manager like PKCS#11, JCE etc.

setup-pkcs11:
  extends: .traditional-signing
  stage: prepare
  artifacts:
    reports:
      dotenv: build.env

sign-jar:
  extends: .setup-stm
  stage: sign
  needs:
    - setup-pkcs11
  script:
    - 'smctl sign --input myapp.jar --keypair-alias your-keypair-alias --config-file $PKCS11_CONFIG -v'
  artifacts:
    paths:
      - myapp.jar

Windows templates

.simple-signing-windows - Simple signing for Windows (supports bulk signing of directories)
.traditional-signing-windows - Traditional signing with PKCS#11, KSP, and CSP and more (PowerShell)

Note

To setup a GitLab runner, see https://docs.gitlab.com/runner/install/.

Example 4. Simple signing

sign-exe:
  extends: .simple-signing-windows
  stage: sign
  tags:
    - windows
  variables:
    INPUT: "Release\\MyApp.exe"
    KEYPAIR_ALIAS: "windows-signing-key"
    DIGEST_ALG: "SHA-256"
  artifacts:
    paths:
      - Release\MyApp.exe

Example 5. Traditional signing - with third-party signing tools

setup-pkcs11-windows:
  extends: .traditional-signing-windows
  stage: prepare
  tags:
    - windows
  artifacts:
    reports:
      dotenv: build.env

sign-with-signtool:
  extends: .setup-stm-windows
  stage: sign
  tags:
    - windows
  needs:
    - setup-pkcs11-windows
  script:
    - 'smctl sign --input MyApp.exe --keypair-alias windows-signing-key --config-file $env:PKCS11_CONFIG -v'
  artifacts:
    paths:
      - MyApp.exe

Example 6. Windows signtool integration

The .traditional-signing-windows template automatically sets up multiple signing interfaces:

PKCS#11 - For use with SMCTL and third-party tools that support PKCS#11
KSP (Key Storage Provider) - Native Windows interface for SignTool and other Windows tools
CSP (Cryptographic Service Provider) - Legacy Windows interface for compatibility

After running .traditional-signing-windows, all Software Trust Manager libraries are set up and authenticated. You can now use your third-party signing tools directly (such as SignTool, jarsigner, and others) as they will automatically integrate with the installed providers.

Note

The /kc parameter references the keypair alias from Software Trust Manager. The DigiCert smtools MSI automatically sets up the KSP provider, making your keypair aliases available to SignTool.

sign-with-signtool:
  extends: .traditional-signing-windows
  stage: sign
  tags:
    - windows
  variables:
    KEYPAIR_ALIAS: "windows-signing-key"
  script:
    - 'Write-Host "Signing with Windows SignTool..."'
    - 'signtool sign /kc "[{{$env:KEYPAIR_ALIAS}}]" /fd SHA256 /tr http://timestamp.digicert.com /td SHA256 bin\MyWindowsApp.exe'
  artifacts:
    paths:
      - bin\MyWindowsApp.exe

Samples: Complete pipelines

Example 7. Example 1: Simple signing with bulk Mode

include:
  - remote: 'https://gitlab.com/your-namespace/digicert-signing-template/-/raw/main/templates/digicert-signing.yml'

stages:
  - build
  - sign
  - deploy

variables:
  KEYPAIR_ALIAS: "my-prod-key"

build-app:
  stage: build
  script:
    - echo "Building application..."
    - make build
  artifacts:
    paths:
      - dist/
    expire_in: 1 day

sign-binaries:
  extends: .simple-signing
  stage: sign
  variables:
    INPUT: "dist/"
    BULK_SIGN_MODE: "true"
    FAIL_FAST: "true"
    DIGEST_ALG: "SHA-256"
    TIMESTAMP: "true"
  dependencies:
    - build-app
  artifacts:
    paths:
      - dist/
    expire_in: 30 days

deploy-signed:
  stage: deploy
  script:
    - echo "Deploying signed artifacts..."
    - ./deploy.sh dist/
  dependencies:
    - sign-binaries
  only:
    - main
    - tags

Example 8. Example 2 : Traditional signing with PKCS#11

include:
  - remote: 'https://gitlab.com/your-namespace/digicert-signing-template/-/raw/main/templates/digicert-signing.yml'

stages:
  - build
  - prepare
  - sign
  - deploy

variables:
  KEYPAIR_ALIAS: "my-prod-key"

build-app:
  stage: build
  script:
    - make build
  artifacts:
    paths:
      - dist/

setup-signing:
  extends: .traditional-signing
  stage: prepare
  artifacts:
    reports:
      dotenv: build.env

sign-binaries:
  extends: .setup-stm
  stage: sign
  needs:
    - build-app
    - setup-signing
  script:
    - 'smctl sign --input dist/ --keypair-alias my-prod-key --config-file $PKCS11_CONFIG -v'
  artifacts:
    paths:
      - dist/
    expire_in: 30 days

deploy-signed:
  stage: deploy
  script:
    - echo "Deploying signed artifacts..."
    - ./deploy.sh dist/
  dependencies:
    - sign-binaries

Example 9. Example 3 : Multi-platform signing (traditional signing use case)

.sign-common:
  stage: sign
  variables:
    KEYPAIR_ALIAS: "multi-platform-key"

sign-linux:
  extends:
    - .simple-signing
    - .sign-common
  tags:
    - linux
  variables:
    INPUT: "build/linux/app"

sign-windows:
  extends:
    - .simple-signing-windows
    - .sign-common
  tags:
    - windows
  variables:
    INPUT: "build\\windows\\app.exe"

sign-macos:
  extends:
    - .simple-signing
    - .sign-common
  tags:
    - macos
  variables:
    INPUT: "build/macos/app.dmg"

Example 10. Example 4 : Conditional signing (traditional signing use case -production only)

sign-production:
  extends: .simple-signing
  stage: sign
  variables:
    INPUT: "build/app"
    KEYPAIR_ALIAS: "prod-key"
  rules:
    - if: '$CI_COMMIT_BRANCH == "main"'
    - if: '$CI_COMMIT_TAG =~ /^v\d+\.\d+\.\d+$/'
  artifacts:
    paths:
      - build/app

Security Best Practices

Protect sensitive variables

Mark SM_API_KEY and SM_CLIENT_CERT_PASSWORD as masked.
Mark all signing variables as protected.
Use protected branches for production signing.

Secure certificate storage

Always use GitLab Secure Files for certificates.
Never commit certificates to Git repositories.
Rotate certificates before expiration.

Audit and logging

Review signing job logs regularly.
Monitor DigiCert console for signing activity.
Set up alerts for unusual activity.

Access control

Limit who can modify CI/CD variables.
Use protected branches for production pipelines.
Implement approval gates for deployments.

Troubleshooting

For common errors and solutions, see Troubleshooting chapter.

In this section: