Introducing project context restrictions for GitLab organizations. This feature enables project-based restrictions on contexts for standalone projects that are not tied to a VCS. Standalone projects are available at this time only with a GitLab integration with CircleCI. In this blog post, we hope to explain the value of this feature and how it can be used to further secure your workflows.
What are project restrictions?
Contexts provide a mechanism for securing and sharing environment variables across projects. By default contexts are unrestricted on CircleCI. Some of you may already be familiar with the context restrictions available to GitHub organizations in the form of security groups. The security groups restriction was built on top of GitHub’s “teams” and allows users to restrict their contexts to certain groups of people.
Because the security group restriction is currently available only for GitHub organizations, we wanted to provide a way for users to secure contexts within their GitLab organizations. Project restrictions allow a user to restrict a context and its environment variables to one or more projects. This means that any workflows under projects the context is not restricted to will not have access to the context and its environment variables during runtime. Jobs will simply fail with an Unauthorized status if they attempt to use a restricted context.
Why use project restrictions?
Without restrictions, secrets stored in contexts are shared organization-wide by default. Project restricted contexts allow CircleCI users to adhere to higher security standards by further securing their CI/CD pipelines. Project restrictions provide a safer way to grant access to secrets across an organization. They can be managed entirely by Org Admins, who have the ability to create, modify, and delete project restrictions.
With group restrictions, a privileged user is needed to initiate the pipeline so the context to be used. Project restrictions improve on group restrictions by allowing approved code to run (based on the project’s triggers and config), regardless of which user actually merged the upstream PR.
With org-wide contexts, a project’s workflow can use a context even if it doesn’t need that context; your JavaScript library’s workflow can use the context for something unrelated, like the credentials for your Maven repository. With project context restrictions, you can enforce which projects need which credentials. Your JavaScript library needs only the context with the npm access token; it doesn’t need the context with the credentials for your Maven repository.
Project restrictions also work great with Project roles. Any Org Contributor can create a project, which would in turn makes them a Project Admin. By adding restrictions, we enable only the Org Admin to restrict context access for “approved” projects. However, anyone assigned a Project Admins role can then decide how a project is triggered, which config it uses, and how its jobs will use the secrets it has access to. With a combination of project restrictions and roles, users are able to improve the security and configuration of their pipelines with even more granularity.
How to use project restrictions
You can access project restrictions from the Contexts page in Organization Settings, where Environment Variables are also found. Follow the steps below to set up your own project restrictions.
You must be an Org Admin to restrict a context through this method. If you do not have Admin privileges, the Add Project Restriction button will be unavailable. Depending on your role, you may be able to view the list of restrictions.
Go to the Organization Settings > Contexts page of your GitLab organization in the CircleCI web app. The list of contexts will be available.
- Select the name of an existing context, or click the Create Context button if you want to use a new context.
- Click the Add Project Restriction button to view the dialog box.
- Select the project name to add to the context, and click the Add button. Use of the context is now limited to the specified project. Currently, multiple projects must be added individually.
- A list of the defined project restrictions is shown on the context page.
- If you have environment variables, they should also appear on the page. If there are none, you can click Add Environment Variables to add them to the context. Then click the Add button to finish. Use of these environment variables is now limited to the projects specified above.
Only workflows under the specified projects may now use the context and its environment variables. A more detailed how-to on setting up and using this feature can be found here.
What’s next?
Beyond project based restrictions, we would like to provide even more fine-grained ways to secure contexts in the future. Some extensions to this feature that we are considering are branch and tag-based restrictions.
Questions and comments
If you have ideas about how to improve this feature or other restrictions you would like, visit Canny to browse or submit new ideas. Currently, this is being offered for GitLab organizations only, but if you have feedback about whether the extension of this feature would be useful for other VCS organizations, we would love to hear your thoughts.
You can also check out our community forum, Discuss, to let us know how you’re using project restrictions. For more detailed information about the feature, visit the docs.
