Contexts provide a mechanism for securing and sharing environment variables across projects. The environment variables are defined as name/value pairs and are injected at runtime. This document describes creating and using contexts in CircleCI in the following sections:
- Renaming orgs and repositories
- Creating and using a context
- Combining contexts
- Restricting a context
- Removing groups from contexts
- Adding and removing users from teams and groups
- Adding and removing environment variables from restricted contexts
- Deleting a context
- Environment variable usage
- Secrets masking
Create and manage contexts on the Organization Settings page of the CircleCI application. You must be an organization member to view, create, or edit contexts. After a context has been created, you can use the
context key in the workflows section of a project
config.yml file to give any job(s) access to the environment variables associated with the context, as shown in the image below.
To use environment variables set on the Contexts page, the person running the workflow must be a member of the organization for which the context is set.
Context names must be unique for each GitHub or Bitbucket organization. Note: Contexts created with the initial default name of
org-global will continue to work.
Context naming for CircleCI server
For any GitHub Enterprise (GHE) installation that includes multiple organizations, the context names across those organizations must be unique. For example, if your GHE is named Kiwi and includes two organizations, you cannot add a context called
deploy to both organizations. That is, the
deploy context name cannot be duplicated in two orgs that exist in the same GHE installation for the Kiwi account. Duplicate contexts within an account will fail with an error.
Renaming orgs and repositories
If you find you need to rename an org or repo that you have previously hooked up to CircleCI, best practice is to follow these steps:
- Rename org/repo in VCS.
- Head to the CircleCI application, using the new org/repo name, for example,
- Confirm that your plan, projects and settings have been transferred successfully.
You are then free to create a new org/repo with the previously-used name in your VCS, if desired.
Note: If you do not follow these steps, it is possible that you may lose access to your org or repo settings, including environment variables and contexts.
Creating and using a context
Using the new version of the CircleCI application, navigate to the Organization Settings page by clicking on the link in the sidebar.
Note: Organization members can create a context, but only organization administrators can restrict it with a security group. The one exception to this case is Bitbucket organizations, which require a user to have the
create repositoriesworkspace permission, regardless of their other permissions on the workspace or the repositories it contains.
Note: If you are using CircleCI Server, Organization Settings can still be accessed as normal using the Settings link in the main navigation.
Click the Create Context button and add a unique name for your Context. After you click the Create Context button in the dialog box, the Context appears in a list with Security set to
All membersto indicate that anyone in your organization can access this Context at runtime.
Click the Add Environment Variable button and enter the variable name and value you wish to associate with this context. Click the Add Variable button to save.
contextkey to the
workflowssection of your
config.ymlfile for every job in which you want to use the variable. In the following example, the
run-testsjob will have access to the variables set in the
org-globalcontext. CircleCI Cloud users can specify multiple contexts, so in this example
run-testswill also have access to variables set in the context called
version: 2.1 workflows: my-workflow: jobs: - run-tests: context: - org-global - my-context jobs: run-tests: docker: - image: cimg/base:2020.01 auth: username: mydockerhub-user password: $DOCKERHUB_PASSWORD # context / project UI env-var reference steps: - checkout - run: name: "echo environment variables from org-global context" command: echo $MY_ENV_VAR
version: 2.1 workflows: my-workflow: jobs: - run-tests: context: org-global jobs: run-tests: docker: - image: cimg/base:2020.01 auth: username: mydockerhub-user password: $DOCKERHUB_PASSWORD # context / project UI env-var reference steps: - checkout - run: name: "echo environment variables from org-global context" command: echo $MY_ENV_VAR
Moving a repository that uses a context
If you move your repository to a new organization, you must also have the context with that unique name set in the new organization.
You can combine several contexts for a single job by just adding them to the context list. Contexts are applied in order, so in the case of overlaps, later contexts override earlier ones. This way you can scope contexts to be as small and granular as you like.
Restricting a context
CircleCI enables you to restrict secret environment variables at run time by adding security groups to contexts. Only organization administrators may add security groups to a new or existing context. Security groups are defined by GitHub teams. If you are using CircleCI Server with LDAP authentication, then LDAP groups also define security groups. After a security group is added to a context, only members of that security group who are also CircleCI users may access the context and use the associated environment variables.
Organization administrators have read/write access to all projects and have unrestricted access to all contexts.
The default security group is
All members and enables any member of the organization who uses CircleCI to use the context.
Note: Bitbucket repositories do not provide an API that allows CircleCI contexts to be restricted, only GitHub projects include the ability to restrict contexts with security groups.
Running workflows with a restricted context
To invoke a job that uses a restricted context, a user must be a member of one of the security groups for the context and must sign up for CircleCI. If the user running the workflow does not have access to the context, the workflow will fail with the
Restrict a context to a security group or groups
You must be an organization administrator to complete the following task.
- Navigate to Organization Settings > Contexts page in the CircleCI app. The list of contexts appears. The default security group is
All membersand allows all users in the org to invoke jobs with that context.
- Click the Create Context button if you wish to use a new context, or click the name of an existing context.
- Click the Add Security Group button to view the dialog box.
- Select GitHub teams or LDAP groups to add to the context and click the Add button. Use of the context is now limited to the selected groups.
- Click Add Environment Variables to add environment variables to the context if none exist and click the Add button. Use of the environment variables for this context is now limited to members of the security groups.
- Navigate to Organization Settings > Contexts in the CircleCI app. The security groups appear in the Security column for the context.
Only members of the selected groups may now use the context in their workflows or add or remove environment variables for the context.
Making changes to context restrictions
Changes to security group restrictions for Contexts might not take effect immediately due to caching. To make sure settings are applied immediately, it is best practice for the Org Administrator to refresh permissions once the change has been made. The Refresh Permissions button can be found on the Account Integrations page.
Administrators of CircleCI Server installations can find the Refresh Permissions button at
Approving jobs that use restricted contexts
Adding an approval job to a workflow gives the option to require manual approval of the use of a restricted context. To restrict running of jobs that are downstream from an approval job, add a restricted context to those downstream jobs, as shown in the example below:
version: 2.1 # Jobs declaration for build, test and deploy not displayed workflows: jobs: build-test-deploy: - build - hold: type: approval # presents manual approval button in the UI requires: - build - test: context: my-restricted-context requires: - build - hold - deploy: context: deploy-key-restricted-context requires: - build - hold - test
In this example, the jobs
deploy are restricted, and will only run if the user who approves the
hold job is a member of the security group assigned to the context
deploy-key-restricted-context. When the workflow
build-test-deploy runs, the
build job will run, then the
hold job, which presents a manual approval button in the CircleCI application. This approval job may be approved by any member, but the jobs
deploy will fail as
unauthorized if the “approver” is not part of the restricted context security group.
Removing groups from contexts
To make a context available only to the administrators of the organization, you may remove all of the groups associated with a context. All other users will lose access to that context.
Adding and removing users from teams and groups
CircleCI syncs GitHub team and LDAP groups every few hours. If a user is added or removed from a GitHub team or LDAP group, it will take up to a few hours to update the CircleCI records and remove access to the context.
Adding and removing environment variables from restricted contexts
Addition and deletion of environment variables from a restricted context is limited to members of the context groups.
Deleting a context
If the context is restricted with a group other than
All members, you must be a member of that security group to complete this task:
As an organization administrator, navigate to the Organization Settings > Contexts page in the CircleCI application.
Click the Delete Context button for the Context you want to delete. A confirmation dialog box appears.
Type Delete and click Confirm. The Context and all associated environment variables will be deleted. Note: If the context was being used by a job in a Workflow, the job will start to fail and show an error.
Environment variable usage
Environment variables are used according to a specific precedence order, as follows:
- Environment variables declared inside a shell command in a
runstep, for example
FOO=bar make install.
- Environment variables declared with the
environmentkey for a
- Environment variables set with the
environmentkey for a job.
- Special CircleCI environment variables defined in the CircleCI Built-in Environment Variables section of this document.
- Context environment variables (assuming the user has access to the Context).
- Project-level environment variables set on the Project Settings page.
Environment variables declared inside a shell command
run step, for example
FOO=bar make install, will override environment variables declared with the
contexts keys. Environment variables added on the Contexts page will take precedence over variables added on the Project Settings page.
Secrets masking is not currently available on self-hosted installations of CircleCI Server
Contexts hold project secrets or keys that perform crucial functions for your applications. For added security CircleCI performs secret masking on the build output, obscuring the
The value of the context will not be masked in the build output if:
- the value of the context is less than 4 characters
- the value of the context is equal to one of
Note: secret masking will only prevent the value of the context from appearing in your build output. The value of the context is still accessible to users debugging builds with SSH.