CircleCI contexts are not just a fancy way to group environment variables; they’re a mechanism for securely distributing secrets across your CI/CD workflows, acting as a centralized, auditable store for sensitive information.
Let’s see this in action. Imagine you have a deployment step that needs AWS credentials to push an artifact to an S3 bucket.
jobs:
deploy:
docker:
- image: cimg/node:14.17.0
steps:
- checkout
- run:
name: Configure AWS Credentials
command: |
aws configure set aws_access_key_id $AWS_ACCESS_KEY_ID
aws configure set aws_secret_access_key $AWS_SECRET_ACCESS_KEY
aws configure set region us-east-1
- run:
name: Deploy to S3
command: aws s3 sync ./dist s3://my-awesome-bucket --delete
To make this work securely, you’d create a CircleCI context named aws-credentials. Inside this context, you’d add two environment variables: AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY, populated with your actual AWS IAM user credentials.
The magic happens when you associate this context with your project. In your CircleCI project settings, under "Contexts," you’d add your aws-credentials context. Then, in your .circleci/config.yml, you’d reference it:
jobs:
deploy:
docker:
- image: cimg/node:14.17.0
steps:
- checkout
- run:
name: Configure AWS Credentials
command: |
aws configure set aws_access_key_id $AWS_ACCESS_KEY_ID
aws configure set aws_secret_access_key $AWS_SECRET_ACCESS_KEY
aws configure set region us-east-1
- run:
name: Deploy to S3
command: aws s3 sync ./dist s3://my-awesome-bucket --delete
workflows:
version: 2
build-and-deploy:
jobs:
- build
- deploy:
requires:
- build
context: aws-credentials # <-- This is where the magic happens
When the deploy job runs, CircleCI automatically injects the environment variables defined in the aws-credentials context into the job’s execution environment. Your aws configure command then picks these up, and your deployment proceeds without ever exposing your AWS secrets directly in your config.yml or in plain text within your repository.
The problem this solves is twofold: preventing secrets from being committed to version control and providing a centralized, auditable place to manage them. Instead of scattering API keys and passwords across various projects or .env files, you have one place to manage them. If a key needs to be rotated, you update it in the context, and all projects using that context automatically pick up the new value. This also provides an audit trail: CircleCI logs who added, edited, or removed environment variables within a context, which is crucial for security compliance.
The real power comes from the granular control. You can create different contexts for different sets of secrets (e.g., heroku-deploy, dockerhub-creds, npm-publish-tokens). A single project can utilize multiple contexts, each providing a specific set of credentials needed for different stages of your pipeline. For instance, one context for deploying to staging, and another, with different credentials, for deploying to production. This isolation prevents accidental cross-environment credential leakage.
Many users think contexts are just for grouping; they are actually a sophisticated access control layer. When you add a context to a project, you’re not just making variables available, you’re granting that project’s jobs permission to access those specific secrets. This is particularly powerful when combined with CircleCI’s user permissions. You can restrict who can manage the secrets within a context (e.g., only security team members) while allowing any authorized user to trigger a pipeline that uses those secrets. This separation of duties is a fundamental security best practice.
The next step is to explore how to use these contexts with different authentication providers, like SSH keys for Git operations.