Start Building for Free
CircleCI.comAcademyBlogCommunitySupport

Config policy reference

5 days ago1 min read
Cloud
On This Page

This reference page lists a selection of helpers, or CircleCI-specific funtions that are likely to be useful for you when you are writing your policies. These helpers will lead to cleaner policies with less boilerplate.

The circle-policy-agent package includes built-in functions for common config policy use cases. All policies evaluated by the policy-service, the circle-cli, or the circle-policy-agent will be able to access these functions. This also means the package name circleci.config is reserved.

CircleCI rego helpers

jobs

jobs is a Rego object containing jobs that are present in the given CircleCI config file. It can be utilized by policies related to jobs.

Definition

jobs = []string

Example jobs object:

[
    "job-a",
    "job-b",
    "job-c"
]

Usage

package org

policy_name["example"]

import future.keywords
import data.circleci.config

jobs := config.jobs

require_jobs

This function requires a config to contain jobs based on the job names. Each job in the list of required jobs must be in at least one workflow within the config.

Definition

require_jobs([string])
returns { string }

Usage

package org

import data.circleci.config

policy_name["example"]

require_security_jobs = config.require_jobs(["security-check", "vulnerability-scan"])

enable_rule["require_security_jobs"]

hard_fail["require_security_jobs"]

orbs

orbs is a Rego object containing orbs and versions present in the given config file. It can be utilized by policies related to orbs.

Definition

orbs[string] = string

Example orbs object:

{
    "circleci/security": "1.2.3",
    "circleci/foo": "3.2.1"
}

Usage

package org

import data.circleci.config

policy_name["example"]

my_orbs := config.orbs

require_orbs

This function requires a config to contain orbs based on the orb names. Versions should not be included in the provided list of orbs.

Definition

require_orbs([string])
returns { string: string }

Usage

package org

import data.circleci.config

policy_name["example"]

require_security_orbs = config.require_orbs(["circleci/security", "foo/bar"])

enable_rule["require_security_orbs"]

hard_fail["require_security_orbs"]

require_orbs_version

This function requires a policy to contain orbs based on the orb name and version.

Definition

require_orbs_version([string])
returns { string: string }

Usage

package org

import data.circleci.config

policy_name["example"]

require_orbs_versioned = config.require_orbs_version(["circleci/security@1.2.3", "foo/bar@4.5.6"])

enable_rule["require_orbs_versioned"]

hard_fail["require_orbs_versioned"]

ban_orbs

This function violates a policy if a config includes orbs based on the orb name. Versions should not be included in the provided list of orbs.

Definition

ban_orbs_version([string])
returns { string: string }

Usage

package org

import data.circleci.config

policy_name["example"]

ban_orbs = config.ban_orbs(["evilcorp/evil"])

enable_rule["ban_orbs"]

hard_fail["ban_orbs"]

ban_orbs_version

This function violates a policy if a config includes orbs based on the orb name and version.

Definition

ban_orbs_version([string])
returns { string: string }

Usage

package org

import data.circleci.config

policy_name["example"]

ban_orbs_versioned = config.ban_orbs_version(["evilcorp/evil@1.2.3", "foo/bar@4.5.6"])

enable_rule["ban_orbs_versioned"]

hard_fail["ban_orbs_versioned"]

resource_class_by_project

This function accepts a resource class to project IDs set mapping. The resource classes defined in the mapping will be reserved for its associated projects. Resource classes not included in the mapping will still be available for use by any project.

Definition

resource_class_by_project({
  "$RESOURCE_CLASS": {$PROJECT_IDS...},
  ...
})
returns { ...reasons: string }

Usage

package org

import future.keywords
import data.circleci.config

policy_name["example"]

check_resource_class = config.resource_class_by_project({
  "large": {"$PROJECT_UUID_A","$PROJECT_UUID_B"},
})

enable_rule["check_resource_class"]

hard_fail["check_resource_class"]

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.

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.