How to Use Contexts for Secrets in CircleCI

Contexts are org-level buckets of environment variables you attach to jobs, so multiple projects share secrets under restricted access.

Create a context in organization settings, add variables to it, then reference it with context: on a job in a workflow. Restrict it to security groups for control.

Attach a context to a job

The deploy job gains the context variables; only authorized groups can use that context.

version: 2.1
workflows:
  deploy:
    jobs:
      - build
      - deploy:
          requires: [build]
          context:
            - production-secrets
          filters:
            branches:
              only: main

jobs:
  deploy:
    docker: [{ image: cimg/base:current }]
    steps:
      - run: curl -H "Authorization: Bearer ${DEPLOY_TOKEN}" https://api.example.com

Gotchas

• Restrict contexts to security groups so only trusted workflows read production secrets.
• Project env vars suit one project; contexts suit secrets shared across many.
• You can attach multiple contexts to a job; later ones override same-named variables.

Key takeaways

• Contexts share secrets across projects at the org level.
• Attach with context: and restrict to security groups.
• Multiple contexts merge, with later ones taking precedence.

Related guides