Docs
Start Building for Free
CircleCI.comAcademyBlogCommunitySupport

Config policy reference

2 months ago2 min read
Cloud
Server v4.x
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 names circleci.config and circleci.utils are reserved.

CircleCI config helpers

The following helpers are imported using import data.circleci.config

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([string])
returns { string: string }

Usage

package org

import data.circleci.config

policy_name["example"]

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

enable_hard["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_hard["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_hard["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_hard["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_hard["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_hard["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_hard["rule_contexts_reserved_by_branches"]

CircleCI Utility helpers

The following helpers are imported using import data.circleci.utils

is_parameterized_expression

This function checks any value and returns true if it is a string that contains a parameter expression, otherwise it returns false.

Definition

is_parameterized_expression(value)
return boolean

Usage

is_parameterized_expression("hello world")                      # false
is_parameterized_expression(42)                                 # false
is_parameterized_expression("release-<<parameters.version>>")   # true

get_element_name

This function retrieves the name of an element in a config file. You can use it to retrieve the name of jobs in workflows, steps in jobs, etc. If the element is an object, this function will return the object’s key.

Definition

get_element_name(input.<config_key>)
returns string

Usage

package org

import data.circleci.utils

policy_name["example"]

job_name1 = utils.get_element_name(input.jobs[0])
job_name2 = utils.get_element_name(input.jobs[1])

Consider the following config.yml:

workflows:
  main:
    jobs:
      - lint
      - test:
          context: test-vars

In the policy example above, job_name1 would equal lint and job_name2 would equal test.

to_array

This function casts a value to an array. Array values are left as is and are not cast to Array<Array>.

Definition

to_array(value)
returns array

Usage

package org

import data.circleci.utils

policy_name["example"]

a = utils.to_array("element")   # a is ["element"]
b = utils.to_array(["element"]) # b is ["element"]

to_set

This function casts a value to a set. Array values are cast to a set and deduplicated. Set values are left as is and are not cast to Set<Set>.

Definition

to_set(value)
returns set

Usage

package org

import data.circleci.utils

policy_name["example"]

a = utils.to_set("element")                      # a is {"element"}
b = utils.to_set(["one", "one", "two", "three"]) # b is {"one", "two", "three"}
c = utils.to_set({"element"})                    # c is {"element"}

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.