Access Control
Access Control can be used to provide a capabilities-based configuration for
Terrateam operations. The configuration defines a set of capabilities, such
as plan
and apply
, and which users can perform those operations. Users,
GitHub Teams, and GitHub Repository Collaborator policies are supported.
Terrateam Configuration
Terrateam behavior can be configured via a config.yml
. This file is located in
a directory named .terrateam
at the root of your Terraform repository:
.terrateam/config.yml
.
See Configuration documentation for details.
Configuration
Top-level key: access_control
See Configuration Reference documentation for details.
Key | Type | Description |
---|---|---|
enabled | Boolean | Enabling the access control feature. Default is true . |
apply_require_all_dirspace_access | Boolean | If true then user must have permission to all targeted Dirspaces to trigger an Apply operation. Default is true . |
plan_require_all_dirspace_access | Boolean | If true then user must have permission to all targeted Dirspaces to trigger a Plan operation. Default is false . |
terrateam_config_update | List | Ruleset for which users can trigger a Terrateam operation on a pull request with a Terrateam configuration file change as part of the changeset. Default is ['*'] . |
unlock | List | Ruleset for which users can trigger an Unlock operation on a pull request. Default is ['*'] . |
policies | policies | Access Control policies. |
Default configuration:
access_control:
enabled: true
apply_require_all_dirspace_access: true
plan_require_all_dirspace_access: false
terrateam_config_update: ['*']
unlock: ['*']
policies:
- tag_query: ''
apply: ['*']
apply_autoapprove: []
apply_force: []
apply_with_superapproval: []
plan: ['*']
superapproval: []
Policies
Policies
tag_query
A list of all tags that must be present in a tag set in order to match the policy. See Tags documentation for Tag Query details.
Each tag_query
consists of a map as a value.
The value map has the following attributes:
Key | Type | Description |
---|---|---|
apply | List | Ruleset for which users can trigger an Apply operation. This includes when_modified autoapply. Default is ['repo:maintain'] . |
apply_autoapprove | List | Ruleset for which users can trigger an Apply Auto Approve operation. Default is [] . |
apply_force | List | Ruleset for which users can trigger an Apply Force operation. Default is [] . |
apply_with_superapproval | List | Allows a user to trigger an Apply operation if a user matching the superapproval list has approved the pull request. Default is [] . |
superapproval | List | Define a list of users whose approvals are super approvals. Default is [] . |
plan | List | Ruleset for which users can trigger a Plan operation. This includes when_modified autoplan. Default is ['*'] . |
Security Considerations
The GitHub default branch can only be modified by administrators of the GitHub repository. Access Control configuration is sourced from the default branch to prevent a user from circumventing Access Control policies in their feature branch.
Rule
Every capability has a rule which is a list of rulesets. If any rule matches the user performing the operation, the user has that capability.
Supported rules:
Rule | Description |
---|---|
* | Matches anyone. |
user:<username> | Matches user with name <username> . For example, user:alice . |
team:<teamname> | Matches any user who is in team <teamname> . The team name must be a team slug. For example team:sre . |
role:<rolename> | Matches users who are in the defined role in the repository. From least access to most access, the roles for an organization repository are: read , triage , write , maintain , admin . See GitHub Documentation for details. |
Evaluation
Access Control rulesets are evaluated for the following events:
- Pull request:
create
update
merge
- Terrateam commands:
The evaluation of access control applies to the user attempting to perform the operation. It does not evaluate who made the change.
Real-world Scenario
Consider an Autoplan that is executed when a pull request is created or updated.
If user Alice wrote the commits in the git repository, however user Bob created the pull request with the changes from Alice, access control will evaluate if Bob has permission to perform a plan operation, because he is the one creating the pull request.
Similarly, if a pull request was created by Bob but Charlie comments terrateam apply
, access
control will evaluate if Charlie can perform the apply, not Bob.
Super Approval
The supperapproval
and apply_with_superapproval
capabilities support a workflow where the ability
to trigger an Apply operation is restricted unless a specific set of users
have approved the pull request.