Signing packages

Sign activity and automation packages with your organization's certificate and configure Studio, the Orchestrator and Robots to trust it.

VeloPhex uses one signing format for every package: activity packages, workflow automation packages and Python automation packages. A signature is a detached file, velophex/signature.json, stored inside the package next to the manifest. It signs the package identity together with the manifest hash, so a valid signature cannot be moved onto a different package.

How trust works#

Package Rule
VeloPhex packages (VeloPhex.*, Velophex.*) Must be signed by the VeloPhex certificate built into Studio, the Robot and the Orchestrator. An unsigned or differently signed package with a reserved name is refused.
Your packages Signing is optional by default.
Any package with a signature The signature is always verified. A broken or tampered signature is always refused, whatever the policy.

Signers are trusted by pin, not by certificate authority: either the certificate's SHA-256 thumbprint, or an spki-sha256: pin of its public key. Signatures use RSASSA-PSS with SHA-512 or ECDSA with SHA-512. The current signature format (format 2) signs the signing time (signedAt), and verifiers check the certificate as of that time, so a signature stays valid after the certificate expires. Every verifier fails closed.

Prerequisites#

  • A code-signing certificate and private key for your organization, as a PKCS#12 file (.pfx or .p12) or, for Studio, in the current user's Windows certificate store.
  • The certificate's SHA-256 thumbprint.
  • Administrator access to the Orchestrator deployment configuration and to the Robots, to pin the signer.

Sign packages#

StudioPython

Workflow projects. Choose the signing certificate (from the certificate store or a PKCS#12 file) in Studio's publishing settings, and turn on Require signing so that Publish refuses a package it could not sign. See Publish to Orchestrator.

Activity packages. The pack-author build (VeloPhex.ActivityPackage.Build) does not sign packages. To use an unsigned activity package, add the feed that holds it in Studio's Package Manager > Settings and mark that source as trusted. If you do sign activity packages, sign once, before first distribution: signing changes the package hash that project lock files pin.

Sign while packing (signing needs the cryptography package in the project environment; see Package and publish Python automations):

PowerShellCopy
$env:VELOPHEX_SIGNING_PASSWORD = "<password>"
uv run velophex pack --sign C:\keys\automation-signing.pfx

The CLI prints Pin this signer as SHA-256 <thumbprint>. Use that value when you configure trust below. It warns when the certificate is expired or not yet valid, because every verifier would refuse the signature.

Trust your signer#

Configure the pin everywhere packages are checked, and turn on the requirement last. If you require signatures before the pin is in place, every job is refused until it lands.

1. Pin the signer on the Orchestrator#

Set your thumbprint in the deployment's .env and recreate the api container:

.envBashCopy
VELOPHEX_ORG_SIGNER_THUMBPRINT=<sha256-thumbprint>
BashCopy
docker compose -f docker-compose.core.yml up -d api

Packages signed by that certificate are then shown as trusted.

2. Pin the signer on every Robot#

At install time:

PowerShellCopy
msiexec /i VeloPhex.Desktop-<version>-win-x64.msi /qn TRUSTEDSIGNERS=<sha256-thumbprint>

On an installed Robot, from an elevated prompt:

PowerShellCopy
& "$env:ProgramFiles\VeloPhex\Robot\VeloPhex.Robot.Service.exe" configure --trusted-signers <sha256-thumbprint>

Separate several thumbprints with commas, for example during a certificate rotation. An empty value (--trusted-signers "") clears the list. A running service picks up the change without a restart.

3. Require signatures (optional)#

When every package you run is signed and every Robot has the pin:

PowerShellCopy
& "$env:ProgramFiles\VeloPhex\Robot\VeloPhex.Robot.Service.exe" configure --require-signed true

or REQUIRESIGNED=1 at install time (the default is 0). A Robot with this setting refuses any automation package that is not signed by a trusted signer.

On the Orchestrator, the equivalent setting is Packages__RequireSignedPackages in the api service's environment in docker-compose.core.yml (shipped as "false").

Verify#

  1. Publish a signed package. In the Orchestrator, open the package version. You should see it reported as signed by a trusted signer.
  2. On a Robot, run VeloPhex.Robot.Service.exe status and check the service log at start-up. The Robot logs its trust posture every time it starts. With the requirement on, you should no longer see the line saying unsigned automation packages are accepted.
  3. Start a job from the signed package. It should run normally.

Rotate a signing certificate#

  1. Get the new certificate and its thumbprint.
  2. Add the new thumbprint next to the old one on every Robot (--trusted-signers old,new) and in the Orchestrator configuration.
  3. Start signing new packages with the new certificate.
  4. Remove the old thumbprint only when no package you still run depends on it. Because format 2 signatures carry their signing time, existing packages stay valid after the old certificate expires as long as its pin is still trusted.

Next steps#

How trust works

Prerequisites

Sign packages

Trust your signer

1. Pin the signer on the Orchestrator

2. Pin the signer on every Robot

3. Require signatures (optional)

Verify

Rotate a signing certificate

Next steps