Apply Requirements and Overrides

apply_requirements in .stategraph/config.yml sets the checks that a pull request must pass before Stategraph Orchestration runs a stategraph apply, such as approvals, no merge conflicts, and passing status checks. They do not stop the autoapply after a merge. Access control sets who can override them.

By default, an apply has two requirements:

• The pull request has no merge conflicts.
• All status checks of the pull request passed.

Configuring Apply Requirements

apply_requirements:
  create_pending_apply_check: true
  checks:
    - tag_query: ""
      approved:
        enabled: true
        any_of: ["user:jane", "user:john"]
        any_of_count: 1
        all_of: []
      merge_conflicts:
        enabled: true
      status_checks:
        enabled: true
        ignore_matching:
          - "ci/.*"

With this configuration, an apply needs:

• At least 1 approval from jane or john.
• No merge conflicts.
• Passing status checks. Status checks that match the regular expression ci/.* do not count.

To set different requirements for different directories or workspaces, use one check entry for each tag_query:

apply_requirements:
  checks:
    - tag_query: "dir:tf1"
      approved:
        enabled: true
        all_of: ["user:jane"]
    - tag_query: "dir:tf2"
      approved:
        enabled: true
        all_of: ["user:john"]

Here, a change in tf1 needs an approval from jane, and a change in tf2 needs an approval from john.

apply_requirements Keys

Check Entry Keys

This entry requires the apply after the merge, and permits an apply of a draft pull request:

apply_requirements:
  checks:
    - tag_query: ""
      apply_after_merge:
        enabled: true
      require_ready_for_review_pr: false

approved Check Keys

The rules use the syntax of access control rules.

CODEOWNERS Enforcement (require_completed_reviews)

With require_completed_reviews: true, Orchestration blocks the apply until GitHub reports the pull request as approved. CODEOWNERS then gates the apply, not only the merge.

apply_requirements:
  checks:
    - tag_query: ''
      approved:
        enabled: true
        require_completed_reviews: true

Orchestration does not parse CODEOWNERS. It reads the review verdict of GitHub for the pull request, so the apply gate and the merge gate of GitHub always agree:

• An approval from any one owner of a path satisfies that path (GitHub rules). When two teams own the same file, one approval is enough.
• .stategraph/config.yml does not need to repeat your CODEOWNERS file. A change to CODEOWNERS takes effect immediately.

For a verdict that includes code owners, the target branch needs a branch protection rule or ruleset with Require review from Code Owners. Two other cases:

• The branch requires reviews, but not from code owners. The verdict counts approvals and ignores who gave them, so require_completed_reviews enforces only the approval count.
• The branch requires no reviews. GitHub gives no verdict. Orchestration then requires that the pull request has no open review request.

On GitLab, require_completed_reviews always requires no open review request, because GitLab has no verdict. Each reviewer of the merge request counts as an open review request, whatever the review state.

For scoped examples, see the CODEOWNERS enforcement guide.

Apply Requirements on GitLab

On GitLab, Orchestration checks each requirement against the merge request:

• approved: an approval comes from a user who approved the merge request, or from a reviewer with the review state reviewed. The user:, team:, and role: rules match GitLab usernames, groups, and project roles. See GitLab users, groups, and roles.
• merge_conflicts: passes when GitLab reports the merge request as mergeable, or as blocked only by a pipeline that is running or must succeed. Any other failed GitLab merge check fails it, such as a merge conflict, a draft, unresolved threads, or missing GitLab approvals.
• status_checks: the commit statuses on the latest commit of the merge request, which include the jobs of its pipelines. The Orchestration job terrateam_job and the stategraph apply status do not count. ignore_matching applies to the status names.
• create_pending_apply_check: adds the stategraph apply commit status to the merge request pipeline.

Access Control and Apply Overrides

Access control sets who can run each operation, and who can override the apply requirements. To turn it on, add this to .stategraph/config.yml:

access_control:
  enabled: true

This policy grants each capability:

access_control:
  enabled: true
  apply_require_all_dirspace_access: true
  plan_require_all_dirspace_access: false
  terrateam_config_update: ['*']
  unlock: ['*']
  policies:
    - tag_query: ''
      apply: ['role:maintain']
      apply_autoapprove: ['user:jane']
      apply_force: ['team:sre']
      apply_with_superapproval: ['role:write']
      plan: ['*']
      superapproval: ['user:john']

Grant the override capabilities only to trusted users or groups who know the risks of an apply without its requirements.

Related

• access_control
• default_branch_overrides
• CODEOWNERS enforcement
• Apply after merge