Config policies for self-hosted runner (Open-preview)
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 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.
Prerequisites
-
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 Installing self-hosted runners guide.
-
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 }
The organization ID is required, and is provided with the
--owner-id
flag. To find your organization/user ID, select Organization Settings in the CircleCI web app side bar.
1. Create your policy
-
If you have not already done so, create an empty directory to store your policies. For example:
mkdir ./config-policies
-
Create a new file in this directory for your new policy. Name the file
runner.rego
. -
Copy the following snippet into the
runner.rego
file you just made:package org import data.circleci.config policy_name["runner_policies"] enable_hard["resource_class_check"] resource_class_check = config.resource_class_by_project({ "namespace/resource_class": {"project_UUIDs"}})
In the following steps you will replace
namespace/resource_class
andproject_UUIDs
with one of your self-hosted runner resource classes, and one of your existing projects. Therunner.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
-
Replace
namespace/resource_class
with one of your runner resource classes:-
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 followed the Installing self-hosted runners guide. Here you will see all your available self-hosted runner resource classes.
-
Replace
namespace/resource_class
in therunner.rego
file with the name of the resource class that you would like to restrict.
-
-
Replace
project_UUIDs
with a project ID:-
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. -
Copy the Project ID from the overview page and replace
project_UUIDs
with this project ID.
-
3. Push up your policy bundle
Create and upload the policy bundle using CircleCI CLI:
circleci policy push ./config-policies –owner-id <your-organization-ID>
If the upload was successful, you will see something like the following:
{
“Created”: [“runner_policies”]
}
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
policy_name["runner_policies"]
enable_hard["resource_class_check"]
resource_class_check = config.resource_class_by_project({
"my-namespace/runner-test1": {
"a20ae1c6-d723-4c03-9bb6-01d5b3594e02",
"2accadd0-c832-489e-b837-4de03def0d35"
},
"my-namespace/runner-test2": {
"637f9136-694e-4105-bb43-1028ffb9043e"
}
})
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 guide first).
- 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.