Overview

CircleCI provides several methods for restricting access to contexts, allowing you to control who or what can access sensitive data such as environment variables. These include Expression Restrictions, Config Policies, Project-Based and Security Groups.

Each method enhances security and helps maintain workflow integrity by limiting context usage to authorized jobs or users.

This guide compares these approaches, providing an overview of how each works, their benefits, and potential trade-offs.

Security Group Restrictions (with Org-Level Enforcement) 

We also provide an organization-level setting that enforces security group assignment for all contexts. When enabled, contexts must be assigned to a specific security group before any user within that group can use them.

Important: Enabling this setting on an existing organization may cause pipeline failures if contexts are not already assigned to security groups. Review all context configurations before enabling.

Location: Organization Settings → Security → Context Security Settings

Expression Restrictions

Expression Restrictions allow you to define simple boolean conditions that must evaluate to `true` for a job to access a context. These conditions are written using CircleCI’s logic and syntax, typically referencing pipeline parameters or job metadata.

Pros

• Granular Control: Allows for specific, fine-grained restrictions (e.g., restrict by branch, tag, or commit metadata).
• Ease of Use: Easy to set up and understand without requiring additional tooling.
• Flexibility: Dynamic evaluation of conditions at runtime ensures contexts adapt to pipeline configurations.

Cons

• Limited to Basic Conditions: Expression syntax may be limiting for more complex security rules.
• Hardcoding Logic: Hardcoding restrictions into the pipeline can reduce reusability and complicate maintenance.

Config Policies

Config Policies leverage Open Policy Agent (OPA) and its policy language, Rego, to enforce organization-wide rules on CircleCI configurations, including context access. These policies provide advanced, programmatic restrictions with robust logic support.

Pros

• Centralized Management: Policies are stored and managed in a single location, making them easier to audit and update.
• Rich Logic Support: Supports complex restrictions, including nested conditions and advanced policy evaluation.
• Reusability: Policies can be reused across multiple contexts, pipelines, or projects.
• Automated Testing**: Policies can be tested and published automatically using CircleCI workflows.

Cons

• Requires Scale Plan: Only available to organizations subscribed to CircleCI's Scale Plan.
• Steeper Learning Curve: Requires familiarity with OPA and Rego for writing policies.
• Dependency on Policy Management: Requires maintaining and version-controlling policy files.

Project-Based Restrictions

Project-Based Restrictions limit access to contexts to specific projects or groups. This method provides a straightforward way to control which projects can access sensitive data, ensuring unauthorized pipelines cannot use restricted contexts.

Pros

• Simplicity: Easy to configure without requiring additional syntax or tools.
• Direct Mapping: Restricts access based on the project or user groups, reducing the risk of accidental exposure.
• Compatibility: Available to all CircleCI plans.

Cons

• Limited Flexibility: Lacks dynamic behavior or advanced conditions for restricting access.
• Coarse-Grained: Restrictions apply broadly to projects or groups without fine-grained control.

Choosing the right method

• Use Expression Restrictions if you need quick and straightforward access controls that adapt dynamically at runtime.
• Opt for Config Policies if you require centralized management, complex logic, or organization-wide policies that apply across multiple pipelines and projects, and you are on the Scale Plan.
• Leverage Project-Based Restrictions for simple, project-specific context access control without requiring complex configurations.

Conclusion

Expression Restrictions, Config Policies, and Project-Based Restrictions each provide valuable tools for securing contexts in CircleCI. By understanding their trade-offs, you can choose the method that best fits your organization’s security and workflow needs.

References

• Set an expression restriction
• Manage contexts with config policies
• Project restrictions