Create and manage config policies
The config policies feature is available on the Scale plan and is currently in open preview. |
While the config policies feature is in open preview, a service failure will result in build configurations not being evaluated against policies. This should be taken into consideration before using config policies for compliance purposes. |
Follow the how-to guides on this page to learn how to create and use config policies.
Enable or disable policy evaluation for an organization
Control whether policy evaluation is applied to pipeline configurations within your organization using the --enabled
flag.
-
To enable policy evaluation run the following command. This sets
--enabled
totrue
, which means project configurations will be evaluated against your organization’s policies when pipelines are triggered.:circleci policy settings --enabled=true --owner-id <your-organization-ID>
Example output:
{ "enabled": true }
-
To disable policy evaluation run the following command. This sets
--enabled
tofalse
, which means project configurations will not be evaluated against your organization’s policies when pipelines are triggered.:circleci policy settings --enabled=false --owner-id <your-organization-ID>
Example output:
{ "enabled": false }
The organization ID is required, and is provided with the |
Create a policy
Ensure you have authenticated your version of the CLI with a token, and updated the CLI, before attempting to use the CLI with config policies. See the Installing the Local CLI page for more information. |
Follow these steps to create a policy that checks the version
of CircleCI config files to ensure it is greater than or equal to 2.1
.
-
Enable config policies for your organization
circleci policy settings --enabled=true --owner-id <your-organization-ID>
Example output:
{ "enabled": true }
-
Create an empty directory to store your policies. For example:
mkdir ./config-policies
-
Inside your new directory create a Rego file for your new policy. Call it:
version.rego
. -
Add the following content to
version.rego
:# All policies start with the org package definition package org policy_name["example"] # signal to circleci that check_version is enabled and must be included when making a decision enable_rule["check_version"] # signal to circleci that check_version is a hard_failure condition and that builds should be # stopped if this rule is not satisfied. hard_fail["check_version"] # define check version check_version = reason { not input.version # check the case where version is not in the input reason := "version must be defined" } { not is_number(input.version) # check that version is number reason := "version must be a number" } { not input.version >= 2.1 # check that version is at least 2.1 reason := sprintf("version must be at least 2.1 but got %v", [input.version]) }
-
Upload your policy to your organization:
circleci policy push ./config-policies --owner-id <your-organization-ID>
Now, when a pipeline is triggered within your organization, the project’s
.circleci/config.yml
will be validated against this policy.
Update a policy
To illustrate making a change to an existing policy, suppose you made an error when creating the policy above. You realize that some project configurations in your organization are using CircleCI config version 2.0
, and you want your policy to reflect this.
-
Change the last check of your rule definition in your
version.rego
file to:{ not input.version >= 2.0 # check that version is at least 2.0 reason := sprintf("version must be at least 2.0 but got %v", [input.version]) }
-
Push the policy directory containing the updated policy file using the CLI (verify the diff, and choose yes when prompted):
circleci policy push ./config-policies --owner-id <your-organization-ID>
Manage policies with your VCS
CircleCI policies are managed by pushing directories of policies to CircleCI via the CLI. The recommended method for managing your policy directory is by storing them in a repository in your VCS, within your organization. This is how policies are managed internally at CircleCI. Pushing a policy bundle is done by triggering a CircleCI pipeline.
We recommend creating a bot account for pushing policies, and using its associated CircleCI personal API token for authentication. For maximum security the token should be stored as an environment variable within a context, and that context should be restricted to groups that are responsible for managing policies. For more information, see the Using Contexts page.
Set up a config policies CI/CD pipeline
-
Set up repository in your VCS to manage policies.
-
Create a directory in your new repo for your Rego policy files, for example:
mkdir ./config-policies
-
Create a
.circleci/config.yml
file for your new policies repository, and copy and paste the config example below. This example pushes policies to CircleCI on commits to themain
branch, and shows a diff of the policy bundle on commits to all other branches:The context for each job is shown as
<my-context>
. This context name is arbitrary, but it must be active and declare the following environment variables:-
CIRCLECI_CLI_TOKEN
with the value of a personal API token to authenticate the CLI -
ORG_ID
with the value of the organization ID
version: 2.1 orbs: circleci-cli: circleci/circleci-cli@0.1.9 # Use orb to make the `circleci-cli/default` executor available for running jobs workflows: main-workflow: jobs: - diff-policy-bundle: context: <my-context> filters: branches: ignore: main # on all branches other than main - push-policy-bundle: context: <my-context> filters: branches: only: main # only on the main branch jobs: diff-policy-bundle: executor: circleci-cli/default resource_class: small steps: - checkout - run: name: Diff policy bundle command: circleci policy diff ./config --owner-id $ORG_ID # show a diff of the policy bundle push-policy-bundle: executor: circleci-cli/default resource_class: small steps: - checkout - run: name: Push policy bundle command: circleci policy push ./config --no-prompt --owner-id $ORG_ID # push the policy bundle to CircleCI
-
Help make this document better
This guide, as well as the rest of our docs, are open source and available on GitHub. We welcome your contributions.
- Suggest an edit to this page (please read the contributing guidefirst).
- To report a problem in the documentation, or to submit feedback and comments, please open an issue on GitHub.
- CircleCI is always seeking ways to improve your experience with our platform. If you would like to share feedback, please join our research community.
Need support?
Our support engineers are available to help with service issues, billing, or account related questions, and can help troubleshoot build configurations. Contact our support engineers by opening a ticket.
You can also visit our support site to find support articles, community forums, and training resources.
CircleCI Documentation by CircleCI is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License.