Secrets

Kod supports per-repository encrypted secrets. Secrets are stored encrypted at rest using AES-256-GCM and automatically injected as environment variables when workflows run.

Prerequisites

To use secrets, you must provide an encryption key when starting the server:

# Generate a key
openssl rand -base64 32

# Start the server with the key
KOD_ENCRYPTION_KEY=your-generated-key kod serve

# Or via CLI flag
kod serve --encryption-key your-generated-key

Don’t lose your encryption key

If you lose the encryption key, stored secrets cannot be recovered. The server will refuse to start if secrets exist in the database but no encryption key is provided.

Managing Secrets

Secrets are managed through the HTTP API. You need a token with secrets:write permission (or admin).

Create or Update a Secret

curl -X PUT http://localhost:3000/repos/my-project/secrets/DEPLOY_TOKEN \
  -H "Authorization: Bearer kod_your_token" \
  -H "Content-Type: application/json" \
  -d '{"value": "my-secret-deploy-token"}'

Secret names must be valid environment variable names: letters, digits, and underscores, starting with a letter or underscore.

List Secrets

curl http://localhost:3000/repos/my-project/secrets \
  -H "Authorization: Bearer kod_your_token"

This returns secret names and metadata only — values are never exposed through the API.

[
  {
    "name": "DEPLOY_TOKEN",
    "repoName": "my-project",
    "createdAt": 1706234567890,
    "updatedAt": 1706234567890
  }
]

Delete a Secret

curl -X DELETE http://localhost:3000/repos/my-project/secrets/DEPLOY_TOKEN \
  -H "Authorization: Bearer kod_your_token"

Using Secrets in Workflows

Secrets are automatically injected into the workflow environment. Reference them like regular environment variables:

[step:deploy]
if: "branch == 'main'"
run: curl -H "Authorization: Bearer $DEPLOY_TOKEN" https://api.example.com/deploy

[step:notify]
run: |
  curl -X POST $SLACK_WEBHOOK \
    -H "Content-Type: application/json" \
    -d '{"text":"Deployment complete"}'

No special syntax or declaration needed. If a secret named DEPLOY_TOKEN exists for the repository, $DEPLOY_TOKEN is available in every step.

Override behavior

Repository secrets override process environment variables with the same name. If the server has DEPLOY_TOKEN=abc in its environment and the repo has a secret DEPLOY_TOKEN=xyz, the workflow sees xyz.

Permissions

Permission	What it allows
secrets:read	List secret names and metadata (no values)
secrets:write	Create, update, and delete secrets
admin	Full access (includes secrets)

Create a token with secrets access:

kod token create ci-manager \
  --permissions repo:read,repo:write,workflow:trigger,secrets:write

Security Details

• Encryption: AES-256-GCM with per-value random IVs
• Key derivation: User-provided key is processed through scrypt for consistent key length
• Storage: Encrypted values stored in PikoDB; never written to disk in plaintext
• API: Secret values are never returned by any API endpoint
• Logging: Decrypted values are never written to logs
• Workflow isolation: Each workflow run gets a fresh clone with secrets injected only into the process environment