Manage secrets and variables

Store secrets and variables used by your workflows in Depot CI. You can limit availability of secrets and variables by repository, branch, workflow, and environment. You can also create variants of secrets and variables with different values depending on the availability you define.

Organization owners manage secrets and variables from the Depot CI Settings in the dashboard or from the CLI.

How secrets are used in workflows

When a Depot CI job starts, secrets are decrypted on demand and dispatched to the sandbox in an isolated VM. The sandbox hydrates the environment with those secrets on a per-step basis as configured in your workflow YAML.

Within an organization, a repository-scoped secret is available only to jobs running for that repository. When multiple secrets have the same name, Depot chooses the most specific matching variant for the job's repository, environment, branch, and workflow file. Secret values are masked in all log output.

For more information about secret encryption and access control, see Understanding security in Depot CI.

Import secrets and variables from GitHub

If you're migrating from GitHub Actions, you can import your existing GitHub secrets and variables into Depot CI with a single command:

depot ci migrate secrets-and-vars

This creates a one-shot GitHub Actions workflow that reads secrets and variables from your GitHub repository and imports them into Depot CI. See depot ci migrate secrets-and-vars in the CLI reference for details.

Manage secrets

You need to be an organization owner to manage secrets. Use the dashboard to create secrets and variables and optionally limit availability by repository, branch, workflow, or environment.

You can also add and remove secrets and variables using the Depot CLI, but you can only scope by repository. To create variants and limit availability by branch, workflow, or environment, you need to use the dashboard.

You can't view secret values after you create them. Variable values are plain text and visible in the dashboard and CLI output.

Names must be non-empty and repository-scoped names can't contain a forward slash (/).

Add a secret

1. From the Depot CI workflows page, click the settings icon.
2. Click Secrets.
3. Click Create secret.
4. Enter a Name, optional Description, and Value for the secret.
5. Optional: Limit availability by repository, branch name, workflow file, or environment.
6. Click Create secret.

Add a variable

1. From the Depot CI workflows page, click the settings icon.
2. Click Variables.
3. Click Create variable.
4. Enter a Name, optional Description, and Value for the variable.
5. Optional: Limit availability by repository, branch name, workflow file, or environment.
6. Click Create variable.

Update secrets and variables

You can update a secret or variable's description, value, and availability from the dashboard.

You can't view secret values after you create a secret, so you can only enter a new value, not view the current value.

1. From the Depot CI workflows page, click the settings icon.
2. Click Secrets or Variables.
3. Find the secret or variable and click its actions menu.
4. Select Edit.
5. Update the fields and click Save.

Remove secrets and variables

1. From the Depot CI workflows page, click the settings icon.
2. Click Secrets or Variables.
3. Find the secret or variable you want to remove and click its actions menu.
4. Select Delete.

Limit availability of secrets and variables

When you create or edit a secret or variable, you can limit its availability by defining the repository, branch, workflow, and environment to which it belongs. This is useful for security-sensitive credentials and configuration where you want to follow the principle of least privilege.

For example, a deployment key in an open source repository might only be needed by deployment workflows, production environments, or release branches. Limiting that secret to trusted contexts keeps it out of untrusted pull request jobs that could try to print secrets from a modified workflow.

Limit availability using one or more kinds of rule:

• Repository: Use when the repository matches (select from the available repos).
• Branch: Use when the branch name matches.
• Workflow: Use when the workflow file matches.
• Environment: Use when the job's GitHub environment name matches exactly. Provides compatibility with GitHub Environment Secrets.

Both branch and workflow rules support glob patterns. For example, release/* or deploy-*.yaml.

Availability gets stricter when you add different kinds of rules and broader when you add alternatives within the same kind of rule. For example, a secret with the following rules:

• Branch rule main
• Branch rule release/*
• Environment rule production

is accessible only when the branch matches main or release/* and the environment field in the workflow YAML matches production.

Using environment rules

An environment rule matches the job's environment field in your workflow YAML. Use an environment rule when a value should be available only to jobs that explicitly run in an environment such as staging or production.

For example, an environment rule with the value production matches the deploy job in the following workflow snippet.

name: Deploy

on:
  push:
    branches:
      - main

jobs:
  deploy:
    runs-on: depot-ubuntu-24.04
    environment: production
    steps:
      - uses: actions/checkout@v4
      - run: ./scripts/deploy.sh

You can also use the object form when you want to attach environment metadata:

jobs:
  deploy:
    runs-on: depot-ubuntu-24.04
    environment:
      name: production
      url: https://app.example.com

Depot uses the environment name for rule matching.

Jobs without an environment field do not match environment rules, even if they run on the same branch or in the same workflow file.

Secret and variable variants

Variants let one secret or variable name resolve to different values depending on the workflow availability you define (by repository, branch, workflow file, environment).

Use variants when the workflow should receive a different value depending on where it runs. For example, you can create:

• A default DATABASE_URL secret or variable for all repositories.
• A release DATABASE_URL secret or variable selected by a branch rule.
• A repository-specific DATABASE_URL secret or variable.
• A production DATABASE_URL secret or variable selected by an environment rule.

You can create, view, and manage all of these variants in the dashboard:

The dashboard always displays variants sorted from least specific to most specific.

Add a variant using the dashboard

1. From the Depot CI workflows page, click the settings icon.
2. Click Secrets or Variables.
3. Find the secret or variable and click its actions menu.
4. Click Add variant.
5. Enter the new Value and optionally update the Description.
6. Add rules to limit availability by repository, branch name, workflow file, or environment.
7. Expand the Secret variants or Variable variants list to view all variants and any conflicts between them.
8. Click Create secret or Create variable.

How multiple variants resolve

Depot resolves matching variants before a workflow starts. A repository-scoped variant is invisible to all other repositories.

When multiple variants match a job, the variants resolve from least to most specific and with the following priority from highest to lowest: environment rules, repository scope, branch rules, workflow rules.

The following table summarizes how variants resolve:

Combining rule types always increases specificity. A variant with both an environment rule and a repository scope beats a variant with only one of them. This means an org-wide variant with an environment rule beats a repository-scoped variant with no environment rule. To resolve to a different value for a specific repo, create a variant scoped to both the repository and the environment.

Preview variant resolution in the dashboard

Use the preview to confirm which variant resolves to your workflow before running it.

1. From the Depot CI workflows page, click the settings icon.
2. Click Secrets or Variables.
3. Click Preview variant resolution to toggle it on.
4. Click a name to expand the secret or variable.
5. Enter the workflow's values to check against (repository, environment, branch, and workflow). The variant that matches the workflow is highlighted in the variant list.

Bulk changes to secrets and variables

Select multiple secrets or variables to delete them or update their availability rules at once.

Bulk delete secrets or variables

1. From the Depot CI workflows page, click the settings icon.
2. Click Secrets or Variables.
3. Select the checkboxes next to each secret or variable you want to delete.
4. Click the trash icon.
5. Click Delete to confirm.

Bulk edit availability rules

Use bulk edit to add, remove, or replace availability rules across multiple secrets or variables at once.

1. From the Depot CI workflows page, click the settings icon.
2. Click Secrets or Variables.
3. Select the checkboxes next to each secret or variable you want to update.
4. Click the edit icon.
5. Choose how to apply the changes:
   • Add rules: adds the rules you specify to all selected items without changing their existing rules.
   • Remove rules: removes the rules you specify from all selected items.
   • Replace all: removes all existing rules from all selected items and replaces them with the rules you specify.
6. Specify the rules to apply and click Save changes.