--- title: "Create and manage config policies" description: "Learn how to write and manage config policies for CircleCI project configurations." platform: "Cloud, Server" doc_version: "Server" last_updated: "2026-10-07" --- > For current CircleCI product defaults, deprecated patterns, and Cloud/Server differences, see [AGENTS.md](https://circleci.com/docs/AGENTS.md). > > For the complete documentation index and site structure, see [llms.txt](https://circleci.com/docs/llms.txt). # Create and manage config policies You must be an organization admin to create and manage config policies. Follow the how-to guides on this page to manage, create, and use config policies. When using the `circleci policy` commands, use the `policy-base-url` flag to provide your CircleCI Server domain. For example: ```shell circleci policy settings --enabled=true --owner-id --policy-base-url ``` ## 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` to `true`, which means project configurations **will** be evaluated against your organization’s policies when pipelines are triggered: ```shell circleci policy settings --enabled=true --owner-id ``` Example output: ```shell { "enabled": true } ``` * To **disable** policy evaluation run the following command. This sets `--enabled` to `false`, which means project configurations **will not** be evaluated against your organization’s policies when pipelines are triggered: ```shell circleci policy settings --enabled=false --owner-id ``` Example output: ```shell { "enabled": false } ``` To find your organization ID and organization slug, select **Org** in the CircleCI web app sidebar to open your organization settings page. The organization ID is available to copy from the org settings overview page. > **Image:** screenshot showing where to find your organization ID Figure 1. Organization ID available in organization settings ## Manage policies with your VCS CircleCI policies are managed by pushing directories of policies to CircleCI via the CLI. Following are recommended best practices: * Store your policies in a repository in your VCS, within your organization. Storing policies in your VCS is how policies are managed internally at CircleCI. Pushing a policy bundle is done by triggering a CircleCI pipeline. * Create a bot account for pushing policies, and use its associated CircleCI personal API token for authentication. For maximum security the token is be stored as an environment variable within a context, and that context must be restricted to groups that are responsible for managing policies. For more information, see the [Using Contexts](https://circleci.com/docs/guides/server/security/contexts/) page. The rest of the steps in this section show how to set up a CI/CD pipeline to manage your policies. ### Prerequisites For the config policies pipeline recommended in this guide you will need to securely manage some 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. You can do this using a context. For more information about setting up and using contexts to securely manage environment variables see the [Using Contexts](https://circleci.com/docs/guides/server/security/contexts/) page. You might already have a context set up for this or you might want to create a new one. For this example the context name `my-context` is used. 1. In the CircleCI web app, select **Organization settings > Contexts**. 2. Select **Create Context** and enter a name for your context, for example `my-context`. 3. Select your new context name in the list to access options. 4. Select **Add Environment Variable**. Enter `CIRCLECI_CLI_TOKEN` for the name, and your personal API token string for the value. For more information, see the [Installing the CircleCI CLI](https://circleci.com/docs/guides/server/toolkit/circleci-cli/) page. Then click **Add Environment Variable** again to complete. 5. Select **Add Environment Variable** and enter `ORG_ID` for the environment variable name, and your organization ID for the value. To find your organization ID and organization slug, select **Org** in the CircleCI web app sidebar to open your organization settings page. The organization ID is available to copy from the org settings overview page. > **Image:** screenshot showing where to find your organization ID Figure 2. Organization ID available in organization settings ### Set up a config policies CI/CD pipeline 1. Set up a repository in your VCS to manage policies. In this example the repository is called `config-policies`. 2. Make a local clone of your repository using your preferred method. 3. Create a directory in your new repository for your Rego policy files, for example: ```shell mkdir ./config-policies ``` 4. Create a `.circleci/config.yml` file for your new policies repository, and copy and paste the config example below. This configuration pushes policies to CircleCI on commits to the `main` branch, and shows a diff of the policy bundle on commits to all other branches: ```yaml 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: pipeline.git.branch != "main" # run the diff-policy-bundle job on every branch except main - push-policy-bundle: context: my-context filters: pipeline.git.branch == "main" # only run the push-policy-bundle job 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-policies --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-policies --no-prompt --owner-id $ORG_ID # push the policy bundle to CircleCI ``` Your file structure will now look something like: ```shell . ├── README.md ├── .circleci └── config.yml └── config-policies ``` 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. For setup steps see the [Prerequisites](#prerequisites) on this page. ## Create a policy Once you have decided how to manage your policies, the next step is to create a policy. Follow the steps in this section to create a policy that checks the `version` of CircleCI config files to ensure `version` is greater than or equal to `2.1`. ### 1\. Write your 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](https://circleci.com/docs/guides/server/toolkit/circleci-cli/) page for more information. 1. [Enable config policies](#config-policy-management-enablement) for your organization, if you have not already done so. 2. If you have followed the steps above to set up CI/CD for your config policies, you will already have a directory for storing your policies. If not, create an empty directory to store your policies. For example: ```shell mkdir ./config-policies ``` 3. Inside your new directory create a Rego file for your new policy. Call it, `version.rego`. 4. Add the following content to `version.rego`: ```go # 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 # Also, signal to circleci that check_version is a hard_failure condition and that builds should be # stopped if this rule is not satisfied. enable_hard["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]) } ``` ### 2\. Push up your policy bundle You can now push your new policy to your organization for it to take effect. You have two options: * Push the policy manually using the CLI from your local environment. * Push your changes to your config policy repository if you are managing policies via your VCS as shown [above](#manage-policies-with-your-vcs). Create and upload the policy bundle using CircleCI CLI: ```shell circleci policy push ./config-policies –-owner-id ``` If the upload was successful, you will see something like the following: ```shell { "Created": ["example"] } ``` Push your changes to `main` and head to the CircleCI web app to see your policy pipeline. This assumes you set up your config policies repository with the sample configuration from the [Config Policies](#manage-policies-with-your-vcs) guide. For policy development, you can push to a development branch. You get a diff of your policy bundle when you push your changes, rather than your new policy being pushed to your CircleCI organization. Now, when a pipeline is triggered within your organization, the project’s `.circleci/config.yml` will be validated against this policy. ### 3\. Update your 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. 1. Change the last check of your rule definition in your `version.rego` file to: ```go { 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]) } ``` 2. Push the policy directory containing the updated policy: Create and upload the policy bundle using CircleCI CLI: ```shell circleci policy push ./config-policies –-owner-id ``` If the upload was successful, you will see something like the following: ```shell { "Created": ["example"] } ``` Push your changes to the `main` branch of your config policies repository. The CircleCI web app will then show your policy pipeline running. For policy development, you can push to a development branch. You get a diff of your policy bundle when you push your changes, rather than your new policy being pushed to your CircleCI organization. ## Next steps If you would like to write tests for your policy, check out the [Test Config Policies](https://circleci.com/docs/guides/server/config-policies/test-config-policies/) guide.