Integrating eSigner with CI/CD Pipelines (A Complete Setup and Configuration Guide)

Scope note: This guide consolidates SSL.com’s existing integration documentation for eSigner CKA (Cloud Key Adapter) and eSigner CodeSignTool. 

1. eSigner CKA vs. CodeSignTool: Which One Do You Need? 

SSL.com’s eSigner platform has two different client tools for CI/CD signing, and picking the right one up front avoids a lot of wasted setup time. 

CI/CD platforms with eSigner CKA guides: GitHub Actions, Azure Pipelines, GitLab CI, Travis CI (all four for .vsix signing), and CircleCI, GitHub Actions, GitLab CI, Travis CI (for .NET DLL signing via signtool.exe). 

CI/CD platforms with eSigner CodeSignTool guides: CircleCI, GitHub Actions, GitLab CI, Travis CI, Jenkins, Azure DevOps, and Bitbucket. 

If your pipeline runs on Linux or macOS runners, or you want one config style that works the same way across every CI/CD tool, use CodeSignTool. If you’re already deep into a Windows-based signtool.exe workflow, CKA will feel more native. 

2. Pre-Integration Checklist (Do This Before Touching CI/CD Config) 

Almost every “signing failed” support ticket traces back to one of these steps being skipped or done out of order. Work through this list top to bottom. 

2.1 SSL.com Account and Certificate 

• Have an active SSL.com account. You’ll authenticate to eSigner with this account’s username and password from inside your pipeline, so use a dedicated service/automation account rather than a personal one where practical. 
• Purchase a code signing certificate that supports eSigner: Both EV Code Signing Certificate and OV Code Signing Certificate can be used for signing.
• Complete organization/identity validation. Automated signing will fail (or never even enroll) if validation is incomplete.
• Enroll the certifiate in eSigner. A certificate that hasn’t been enrolled cannot be used for cloud signing at all — this is the single most common blocker for first-time integrations. Follow Enroll eSigner Remote Document/EV Code Signing to link the certificate to the eSigner cloud service. 

2.2 eSigner Credential and OTP Setup 

• Set up the eSigner Authenticator / TOTP secret. eSigner requires a one-time-password (TOTP) alongside your username and password for every signing call. Follow Automate eSigner EV Code Signing to retrieve your TOTP_SECRET. This is a one-time setup. 
• Find your Credential ID (CodeSignTool only). If your account has more than one eSigner code signing certificate, CREDENTIAL_ID becomes a required parameter— CodeSignTool has no way to guess which certificate you mean. You can retrieve the list of credential IDs tied to your account using the get_credential_ids CodeSignTool command before wiring up your pipeline, so you’re not debugging a missing parameter later. 
• Decide TEST vs. PROD. eSigner has a sandbox (“TEST”/”sandbox”) and production (“PROD”/”product”) environment. Point at TEST while you’re validating your pipeline, and only switch ENVIRONMENT_NAME/MODE to PROD once a full signing round-trip works end to end. Signing in TEST mode does not produce a certificate chain trusted by end users. 

2.3 CI/CD Platform Prerequisites 

• Store credentials as encrypted secrets, never as plaintext pipeline variables. Every platform below has a secrets/protected-variables mechanism (GitHub Actions secrets, GitLab CI/CD variables marked “Masked”, CircleCI project environment variables, Jenkins Credentials, Azure DevOps variable groups/Key Vault, Bitbucket repository variables). Use it for USERNAME, PASSWORD, CREDENTIAL_ID, and TOTP_SECRET. 
• Confirm your runner has the right OS/tooling:
  • eSigner CKA: requires a Windows runner/agent (windows-latest, windows-2019, etc.) because it installs a Windows CNG KSP. It will not run on Linux or macOS images. 
  • eSigner CodeSignTool (Docker route) requires Docker available on the runner (docker service enabled, Docker-in-Docker for GitLab, setup_remote_docker for CircleCI, etc.) and outbound network access to ghcr.io (GitHub Container Registry) and SSL.com’s signing endpoints. 
• Make sure the file you’re signing exists at the build stage before the sign stage runs. Every workflow below is split into a build stage (produces the artifact) and a sign stage (consumes it) — mismatched artifact paths between two stages is the single most common config-only error. 

2.4 Optional: Windows-Specific Prep (eSigner CKA Only) 

• Confirm the Windows SDK / signtool.exe is present on the runner image. Standard windows-latest GitHub/Azure/CircleCI images ship the Windows 10 SDK, but the exact signtool.exe path (x86 vs. x64, and the SDK build number folder) varies by image version — the sample workflows below hard-code a path, and you should verify it against the actual image you’re using. If the x64 binary throws an error, fall back to the x86 build at a path such as C:\Program Files (x86)\Windows Kits\10\bin\<version>\x86\signtool.exe. 
• Know where eSigner CKA installs and logs. The installer writes to a -DIR=path you choose, and writes KSP logs under %APPDATA%\eSignerCKA\KSP — upload that folder as a build artifact so failed signing attempts are diagnosable from CI logs instead of requiring RDP access to the runner. 

Once all of the above is done, pick the tool and platform combination that matches your setup below. 

 

3. eSigner CKA: CI/CD Integration 

3.1 Common Setup Steps (All Platforms) 

Every eSigner CKA workflow, regardless of platform, performs the same five actions: 

• Download and install eSignerCKA in silent mode. 
• Run eSignerCKATool.exe config with your account credentials, TOTP secret, and mode to generate a local master.key. 
• Run eSignerCKATool.exe unload then load to register the certificate into the Windows certificate store. 
• Read the certificate’s thumbprint out of Cert:\CurrentUser\My and pass it to signtool.exe (or OpenVsixSignTool for .vsix packages). 
• Upload the eSignerCKA log folder as a build artifact so failures are debuggable. 

4. eSigner CodeSignTool: CI/CD Integration 

4.1 Common Setup Steps (All Platforms) 

CodeSignTool workflows follow the same two-stage patterns everywhere: a build stage produces the artifact, and a sign stage pulls SSL.com’s codesigner Docker image and signs it. The Docker approach means the same core command works nearly unchanged across CircleCI, GitHub Actions, GitLab CI, Travis CI, Jenkins, Azure DevOps, and BitBucket — only the surrounding pipeline syntax differs. 

Required environment variables/secrets: 

Required inputs: 

5. Sample Workflows 

Example workflows are provided in the following SSL.com guides: 

eSigner CKA: 

• How to Integrate eSigner CKA with CI/CD Tools: Guides are provided for GitHub Actions, Azure Pipeline, GitLab CI, CircleCI, and Travis CI 

eSigner CodeSignTool, per platform: 

• CircleCI 

• GitHub Actions 

• GitLab CI 

• Travis CI 

• Jenkins CI 

• Azure DevOps 

• BitBucket 

6. Troubleshooting Common Errors 

If none of the above resolves an issue, SSL.com support can assist with custom or high-volume signing setups.