Skip to main content

Secrets

Secrets store sensitive values like API keys, database passwords, and access tokens. DevRamps injects secrets at runtime so they never appear in logs, the dashboard, or the deployment plan.

Secret Scopes​

Organization secrets​

Organization secrets are available to all pipelines and all stages in your organization. Use these for values that are the same everywhere (e.g., a third-party API key).

variables:
  stripe_key: ${{ organization.secrets["STRIPE_API_KEY"] }}
  # or equivalently:
  stripe_key: ${{ secret("STRIPE_API_KEY") }}

Stage secrets​

Stage secrets are scoped to a specific stage. Use these for values that differ between environments (e.g., a database password that's different in staging vs. production).

variables:
  db_password: ${{ stage.secrets["DB_PASSWORD"] }}
  # or equivalently:
  db_password: ${{ stage_secret("DB_PASSWORD") }}

Managing Secrets​

Creating a secret​

  1. Go to your organization settings in the DevRamps dashboard.
  2. Navigate to Secrets.
  3. Click Create Secret.
  4. Enter:
    • Name: The secret name (used in expressions).
    • Value: The secret value.
    • Description: (Optional) A description of what the secret is for.
    • Scope: Choose "Organization" for a global secret, or select a specific stage name for a stage-scoped secret.
    • Storage Type: How the secret is stored (see below).
  5. Click Save.

Updating a secret​

Navigate to the secret in the dashboard and update its value. The new value takes effect on the next deployment.

Deleting a secret​

Delete secrets from the dashboard. Make sure no pipelines reference the secret before deleting it, or deployments will fail.

Storage Types​

TypeDescription
Service ManagedDevRamps stores and manages the secret using its own KMS key. Simplest option.
User ManagedThe secret is stored in your AWS CI/CD account using your own KMS key. You retain full control over the encryption key.

User-managed secrets require your organization to have a configured AWS CI/CD account.

How Secrets Are Injected​

Secrets follow a deferred resolution model:

  1. Pipeline synthesis: When your pipeline YAML is processed, secret references are replaced with markers (e.g., [SECRET:STRIPE_API_KEY]). The actual values are never stored in the deployment plan.
  2. Step execution: Just before a step runs, DevRamps retrieves the actual secret values from storage and substitutes them into the step parameters.
  3. Log masking: Secret values are automatically masked in step logs. If a step outputs a secret value, it appears as *** in the logs.

This means secrets are:

  • Never visible in the DevRamps dashboard.
  • Never stored in the deployment plan or database.
  • Only present in memory during step execution.

Referencing Secrets in Pipelines​

There are two equivalent syntaxes for referencing secrets:

Object syntax​

# Organization secret
api_key: ${{ organization.secrets["API_KEY"] }}

# Stage secret
db_pass: ${{ stage.secrets["DB_PASSWORD"] }}

Function syntax​

# Organization secret
api_key: ${{ secret("API_KEY") }}

# Stage secret
db_pass: ${{ stage_secret("DB_PASSWORD") }}

Both syntaxes produce the same result. Use whichever you find more readable.

Secret Naming and Limits​

  • Secret names can contain uppercase letters, lowercase letters, numbers, underscores, and hyphens.
  • Secret names are case-sensitive (API_KEY and api_key are different secrets).
  • Secret values can be any string up to 4KB in size.

Secret rotation​

To rotate a secret, update its value in the DevRamps dashboard. The new value takes effect on the next deployment. There is no built-in automatic rotation — update secret values manually when needed.

User Managed KMS​

When using "User Managed" storage, DevRamps creates a KMS key in your CI/CD account during initial setup. This key is used to encrypt and decrypt all user-managed secrets. The KMS key is a DevRamps managed resource visible in your dashboard.