Start Building for Free

Config policies for self-hosted runner

2 months ago2 min read
Server v4.x
On This Page

Follow this how-to guide to learn how to create a config policy to restrict which projects can run jobs on a self-hosted runner resource class. For more information about config policies, see the Config policies overview.


  • Install/update the CircleCI CLI, and ensure you have authenticated with a token before attempting to use the CLI with config policies. See the Installing the Local CLI page for more information.

  • Set up a self-hosted runner. See the Getting started section of the Self-hosted runners overview.

  • Ensure you have enabled config policy evaluation for your organization so that 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

1. Create your policy

  1. If you have not already done so, create an empty directory to store your policies. For example:

    mkdir ./config-policies
  2. Create a new file in this directory for your new policy. Name the file runner.rego.

  3. Copy the following snippet into the runner.rego file you just made:

    package org
    import data.circleci.config
    resource_class_check = config.resource_class_by_project({ "namespace/resource_class": {"project_UUIDs"}})

    In the following steps you will replace namespace/resource_class and project_UUIDs with one of your self-hosted runner resource classes, and one of your existing projects. The runner.rego policy, once uploaded, will then restrict your specified self-hosted runner to only run jobs from your specified project.

2. Update policy with your details

  1. Replace namespace/resource_class with one of your runner resource classes:

    1. In the CircleCI web app, go to your self-hosted runner’s inventory page by selecting Self-Hosted Runners in the sidebar. If you do not see this option, check that you have accepted the CircleCI Runner Terms and created a namespace and resource class, as outlined in the runner installation guides. Here you will see all your available self-hosted runner resource classes.

    2. Replace namespace/resource_class in the runner.rego file with the name of the resource class that you would like to restrict.

  2. Replace project_UUIDs with a project ID:

    1. In the CircleCI web app, navigate to your projects dashboard by selecting Projects in the sidebar. Find the project you want to allow to build on your self-hosted runner, and then click the ellipsis (…​) next to that project and select Project Settings.

    2. Copy the Project ID from the overview page and replace project_UUIDs with this project ID.

3. 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.

A more complex example

Once you have this runner restriction policy up and running, you can quickly add more runner resource class/project pairings, and allow multiple projects per runner. To do this you will expand the resource_class_check rule.

The following snippet shows two separate runner resource classes (my-namespace/runner-test1 and my-namespace/runner-test2) with allowed projects, the first has two projects in its allowed list.

package org
import data.circleci.config



resource_class_check = config.resource_class_by_project({
  "my-namespace/runner-test1": {
  "my-namespace/runner-test2": {

Suggest an edit to this page

Make a contribution
Learn how to contribute