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. 

	eSigner CKA	eSigner CodeSignTool
What it is	A Windows CNG Key Storage Provider (KSP) that lets signtool.exe, certutil.exe, and similar Windows tools talk to eSigner as if the certificate were installed locally	A Java command-line utility that signs files directly via the eSigner CSC API
Runner OS	Windows only	Linux, Windows, or macOS
File types	.dll, .exe, .msi, .vsix, and anything signtool.exe can sign	.exe, .dll, .msi, .jar, and other Authenticode/Java-signable objects
Best fit	Windows-native pipelines that already call signtool.exe	Cross-platform pipelines, high-volume/batch signing

  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 certificate 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 the 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 eSignerCKA 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 pattern 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: 

Variable	Purpose
USERNAME	SSL.com account username
PASSWORD	SSL.com account password
CREDENTIAL_ID	Credential ID of the signing certificate. Optional only if your account has exactly one eSigner code signing certificate
TOTP_SECRET	OAuth TOTP secret from your eSigner Authenticator setup
ENVIRONMENT_NAME	TEST (sandbox) or PROD (live signing)

Required inputs: 

Input	Purpose
input_file_path	Path of the file to be signed
output_dir_path	Directory the signed file will be written to (omit to overwrite the input file in place)

  

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 

Symptom	Likely Cause	Fix
Credential ID is required / signing fails with no cert selected	Account has more than one eSigner code signing certificate	Run get_credential_ids and set CREDENTIAL_ID explicitly
Signing hangs or times out on TOTP	Wrong or expired TOTP_SECRET, or the eSigner Authenticator wasn’t set up	Re-run the Automate eSigner EV Code Signing setup and regenerate the secret
signtool.exe not found / wrong architecture error (CKA only)	Runner image’s Windows SDK path or bit-width doesn’t match the hard-coded path in the sample	Locate the actual SDK folder on the image (Windows Kits\10\bin\<version>\<x86 or x64>\signtool.exe) and update the path
eSignerCKA install succeeds but no certificate appears in the store	unload/load step skipped, or ran before config finished	Ensure config ? unload ? load run in that exact order, in the same job/step context
Sign stage can’t find the artifact from the build stage	Artifact path mismatch, or artifact not persisted/uploaded between stages	Confirm the exact path used in the build stage’s artifact upload matches the path the sign stage downloads to
Signed file works in TEST but customers still see “unknown publisher”	Still pointed at sandbox	Set ENVIRONMENT_NAME/MODE to PROD once testing is complete, and confirm the certificate itself has completed validation

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