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

`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 access control configuration is always read from the repository default branch.

The GitHub default branch (opens in a new tab) 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`.
`repo:<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 (opens in a new tab) for details.

GitHub team names must be specified using their slug:

The GitHub CLI can be usd to retrieve this value:

$ gh api orgs/<ORG>/teams

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.

Access Control always evaluates if the user who requested the operation has permission.

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.

Use Cases

Locks Apply Requirements