Skip to main content

Trunk-based workflow component

The component requires merge requests to squash their commits when merging into the trunk.

Configure GITLAB_TOKEN with a group service account before allowing the component to update project settings.

Usage​

  • Ensure your projects have a description
  • Set GITLAB_TOKEN as a masked, protected and hidden variable for your group
  • Protect your main branch
  • Create GitLab pipeline file .gitlab-ci.yml:

Set branch-name-rule to a GitLab RE2 regular expression to reject new branch names that do not match your convention. The default empty value leaves an existing project push rule unchanged. Project push rules require GitLab Premium or Ultimate.

Use branch-rules to configure protected branches, access levels, and regular approval rules. Each entry requires branch, allowed-to-merge, and allowed-to-push. Add approvers to select GitLab usernames, group paths that start with /, or the role tokens @@guest, @@reporter, @@developer, @@maintainer, and @@owner. An omitted or empty approvers array selects all project Maintainers and Owners. A wildcard branch such as renovate/* creates an approval rule named renovate.

Use GitLab access level 0 for no access, 30 for Developer, or 40 for Maintainer. Level 60 is available to Administrators on self-managed GitLab. Force pushes are disabled for every configured rule.

When a configured branch contains CODEOWNERS, the component enables Code Owner approval and keeps the regular approval rule. A merge request must satisfy both policies. The component also enables automatic Code Owner reviewer assignment when the GitLab API supports it.

If GitLab exposes a differently named single approval rule, the component reuses it only after verifying that multiple rules are unavailable and the existing rule already provides the same project-wide approval policy. Unverifiable capabilities, API permission failures, or a non-equivalent policy fail configuration without replacing that rule. This verification uses the licensedFeatureAvailability GraphQL field available in GitLab 18.11 or later.

include:
  - component: $CI_SERVER_FQDN/xrow-public/ci-tools/codeowners@stable
    inputs:
      codeowners: |
        [Default]
        * @@maintainer @@owner
  - component: $CI_SERVER_FQDN/xrow-public/ci-tools/workflow-trunkbased@stable
    inputs:
      branch-name-rule: '^(main|master|develop|(feature|feat|bugfix|fix|hotfix|release|chore|ai|copilot|cursor|claude|codex)/[a-z0-9]+(\.[a-z0-9]+)*(-[a-z0-9]+(\.[a-z0-9]+)*)*)$'
      branch-rules:
        - branch: main
          allowed-to-merge: 40
          allowed-to-push: 0
          approvers:
            - alice
            - /root-group/reviewers
            - "@@owner"
        - branch: release/*
          allowed-to-merge: 40
          allowed-to-push: 0
          approvers:
            - "@@maintainer"
            - "@@owner"

The example follows the Conventional Branch formal grammar.

Branching​

Roles​

The following roles exist in the scenarios:

  • Developer
    • Creates a short-lived feature, fix, chore, or hot fix branch
    • Implements the change and keeps it small enough to merge quickly
    • Creates a merge request to the default branch after successful local testing
  • Maintainer
    • Reviews merge requests
    • Merges into the default branch after the pipeline succeeds and discussions are resolved

Settings enabled by default​

  • Protect main; Maintainers can merge and direct pushes are disabled
  • Disable force pushes on main
  • Branch rules
  • fast forward merge
  • Pipelines must succeed before merge
  • Merged results pipelines
  • Skipped pipelines are considered successful
  • All discussions must be resolved
  • Allow merge request authors and committers to approve when at most three active human Maintainers and Owners can approve. Prevent both approval types for larger teams.
  • Remove all approvals when commits are added
  • Prevent editing approval rules in merge requests
  • Create a regular one-approval rule for each configured branch and assign its configured approvers, or all Maintainers and Owners when none are listed.
  • With a CODEOWNERS file, also require Code Owner approval and automatically assign matching Code Owners when the GitLab API supports it.
  • Merge request branch workflow:
    • feat/* -> main
    • fix/* -> main
    • chore/* -> main
    • hotfix/* -> main

Inputs​

NameDescriptionDefaultType
------------
autoconfigure-enabledEnable or disable the automatic configuration of the pipeline.trueboolean
branch-name-ruleRE2 regular expression that every new branch name must match. An empty value leaves the project push rule unchanged.string
branch-rulesProtected branch and approval rules. Each rule can assign approvers by username, /group path, or @@role. Access levels are 0 (no access), 30 (Developer), 40 (Maintainer), or 60 (Administrator on self-managed GitLab).[{"branch":"main","allowed-to-merge":40,"allowed-to-push":0}]array
pattern-branch-interruptibleRegex pattern to mark the pipeline as interruptible based on the branch name. Use https://github.com/google/re2/wiki/Syntax/^(feat|fix|hotfix)\//string
pattern-branch-skipRegex pattern to skip the pipeline based on the branch name. Use https://github.com/google/re2/wiki/Syntaxstring
rulesThe rules that control when the project configuration job runs.[{"if":"$CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH","when":"always"},{"when":"never"}]array