• Docs
  • Features
  • Access Control

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 Runtime 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.


Top-level key: access_control

See Configuration Reference documentation for details.

enabledBooleanEnabling the access control feature. Default is true.
apply_require_all_dirspace_accessBooleanIf true then user must have permission to all targeted Dirspaces to trigger an Apply operation. Default is true.
plan_require_all_dirspace_accessBooleanIf true then user must have permission to all targeted Dirspaces to trigger a Plan operation. Default is false.
terrateam_config_updateListRuleset 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 ['*'].
unlockListRuleset for which users can trigger an Unlock operation on a pull request. Default is ['*'].
policiespoliciesAccess Control policies.

Default configuration:

  enabled: true
  apply_require_all_dirspace_access: true
  plan_require_all_dirspace_access: false
  terrateam_config_update: ['*']
  unlock: ['*']
    - tag_query: ''
      apply: ['*']
      apply_autoapprove: []
      apply_force: []
      apply_with_superapproval: []
      plan: ['*']
      superapproval: []



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:

applyListRuleset for which users can trigger an Apply operation. This includes when_modified autoapply. Default is ['repo:maintain'].
apply_autoapproveListRuleset for which users can trigger an Apply Auto Approve operation. Default is [].
apply_forceListRuleset for which users can trigger an Apply Force operation. Default is [].
apply_with_superapprovalListAllows a user to trigger an Apply operation if a user matching the superapproval list has approved the pull request. Default is [].
superapprovalListDefine a list of users whose approvals are super approvals. Default is [].
planListRuleset 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 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.


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:

*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 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


Access Control rulesets are evaluated for the following events:

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