Docs
Start Building for Free
CircleCI.comAcademyBlogCommunitySupport

Config policy reference

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

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

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"]

contexts_allowed_by_project_ids

This function accepts project ids (PROJECTS) and context names (ALLOWED_CONTEXTS) as one of the following types:

  • string

  • set of strings

  • array of strings

It prevents the usage of any context not in ALLOWED_CONTEXTS for all projects that are in PROJECTS.

Definition

contexts_allowed_by_project_ids(
  PROJECTS: string | Array<string> | Set<string>
  ALLOWED_CONTEXTS: string | Array<string> | Set<string>
)
returns reason <type string>

Usage

package org

import future.keywords
import data.circleci.config

policy_name["a_unique_policy_name"]

rule_contexts_allowed_by_project_ids = config.contexts_allowed_by_project_ids(
  ["${PROJECT_1_UUID}","${PROJECT_2_UUID}"],
  ["${ALLOWED_CONTEXT_NAME_1}","${ALLOWED_CONTEXT_NAME_2}"]
)

enable_rule["rule_contexts_allowed_by_project_ids"]

hard_fail["rule_contexts_allowed_by_project_ids"]

contexts_blocked_by_project_ids

This function accepts project IDs (PROJECTS) and context names (BLOCKED_CONTEXTS) as one of the following types:

  • string

  • set of strings

  • array of strings

It blocks the usage of any context in BLOCKED_CONTEXTS for all projects in PROJECTS.

Definition

contexts_blocked_by_project_ids(
  PROJECTS: string | Array<string> | Set<string>
  BLOCKED_CONTEXTS: string | Array<string> | Set<string>
)
returns reason: string

Usage

package org

import future.keywords
import data.circleci.config

policy_name["a_unique_policy_name"]

rule_contexts_blocked_by_project_ids = config.contexts_blocked_by_project_ids(
  ["${PROJECT_1_UUID}","${PROJECT_2_UUID}"],
  ["${BLOCKED_CONTEXT_1}","${BLOCKED_CONTEXT_2}"]
)

enable_rule["rule_contexts_blocked_by_project_ids"]

hard_fail["rule_contexts_blocked_by_project_ids"]

contexts_reserved_by_project_ids

This function accepts project ids (PROJECTS) and context names (RESERVED_CONTEXTS) as one of the following types:

  • string

  • set of strings

  • array-of-strings

It blocks the usage of any context in RESERVED_CONTEXTS for all projects not in PROJECTS.

Definition

contexts_reserved_by_project_ids(
  PROJECTS: string | Array<string> | Set<string>
  RESERVED_CONTEXTS: string | Array<string> | Set<string>
)
returns reason: string

Usage

package org

import future.keywords
import data.circleci.config

policy_name["a_unique_policy_name"]

rule_contexts_reserved_by_project_ids = config.contexts_reserved_by_project_ids(
  ["${PROJECT_1_UUID}","${PROJECT_2_UUID}"],
  ["${RESERVED_CONTEXT_1}","${RESERVED_CONTEXT_2}"]
)

enable_rule["rule_contexts_reserved_by_project_ids"]

hard_fail["rule_contexts_reserved_by_project_ids"]

contexts_reserved_by_branches

This function accepts VCS branch names (BRANCHES) and context names (RESERVED_CONTEXTS) as one of the following types:

  • string

  • set-of-strings

  • array-of-strings

Branch names not in BRANCHES are not allowed to use the contexts in RESERVED_CONTEXTS, however, other contexts may be used.

Definition

contexts_reserved_by_branches(
  BRANCHES: string | Array<string> | Set<string>
  CONTEXT_LIST: string | Array<string> | Set<string>
)
returns reason: string

Usage

package org

import future.keywords
import data.circleci.config

policy_name["a_unique_policy_name"]

rule_contexts_reserved_by_branches = config.contexts_reserved_by_branches(
   ["${BRANCH_1}, "${BRANCH_2}", "${BRANCH_3}"]",
  ["${RESERVED_CONTEXT_1}","${RESERVED_CONTEXT_2}"]
)

enable_rule["rule_contexts_reserved_by_branches"]

hard_fail["rule_contexts_reserved_by_branches"]

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.

Creative Commons License

CircleCI Documentation by CircleCI is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License.