--- title: "Config policy reference" description: "Open preview of config policies for CircleCI. Reference page for function helpers." doc_version: "unversioned" last_updated: "2026-09-22" --- > For the complete documentation index, see [llms.txt](https://circleci.com/docs/llms.txt) # Config policy reference The config policies feature is available on the **Scale** Plan and from CircleCI Server v4.2. You must be an organization admin in order to create and manage config policies. This reference page lists a selection of _helpers_, or CircleCI-specific functions 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 ```go orbs[string] = string ``` Example `orbs` object: ```json { "circleci/security": "1.2.3", "circleci/foo": "3.2.1" } ``` #### Usage ```go 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 must not be included in the provided list of orbs. #### Definition ```go ban_orbs([string]) returns { string: string } ``` #### Usage ```go 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 ```go ban_orbs_version([string]) returns { string: string } ``` #### Usage ```go 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 ```go resource_class_by_project({ "$RESOURCE_CLASS": {$PROJECT_IDS...}, ... }) returns { ...reasons: string } ``` #### Usage ```go 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 ```go contexts_allowed_by_project_ids( PROJECTS: string | Array | Set ALLOWED_CONTEXTS: string | Array | Set ) returns reason: string ``` #### Usage ```go 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 ```go contexts_blocked_by_project_ids( PROJECTS: string | Array | Set BLOCKED_CONTEXTS: string | Array | Set ) returns reason: string ``` #### Usage ```go 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 ```go contexts_reserved_by_project_ids( PROJECTS: string | Array | Set RESERVED_CONTEXTS: string | Array | Set ) returns reason: string ``` #### Usage ```go 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 ```go contexts_reserved_by_branches( BRANCHES: string | Array | Set CONTEXT_LIST: string | Array | Set ) returns reason: string ``` #### Usage ```go 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 ```go is_parameterized_expression(value) return boolean ``` #### Usage ```go is_parameterized_expression("hello world") # false is_parameterized_expression(42) # false is_parameterized_expression("release-<>") # 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 ```go get_element_name(input.) returns string ``` #### Usage ```go 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: ```yaml 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. #### Definition ```go to_array(value) returns array ``` #### Usage ```go 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. #### Definition ```go to_set(value) returns set ``` #### Usage ```go 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"} ```