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:
  • terrateam plan
  • terrateam apply
  • terrateam apply-force
  • terrateam apply-autoapprove
  • terrateam unlock

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.