Skip to main content

Set up Merge Request Workflow (for GitLab)

Introduction​

This guide walks you through setting up the Merge Request (MR) Workflow in Holistics for GitLab repositories.

How to set up​

How it works

Holistics uses a GitLab Access Token to:

  • Create Merge Requests in your repository
  • Monitor MR status (open, closed, or merged)
  • Automatically publish changes when MRs are merged to the master branch

Prerequisites​

Before setting up the MR workflow, ensure you have:

Step 1: Enable MR workflow in Holistics​

  1. Navigate to Settings > Project Settings > Git Integration
  2. Toggle on Enable MR Workflow
  3. You'll be prompted to add a GitLab Access Token

Step 2: Create GitLab access token​

Choose the appropriate token type for your needs:

  • Project access token (Recommended): Scoped to a specific repository, more secure for production use
  • Personal access token: Tied to your user account, works across multiple projects but has broader permissions
  1. In your GitLab project, go to Settings > Access tokens
  2. Click Add new token and configure:
    • Token name: Holistics MR Integration
    • Expiration date: Set to 90 days (you'll receive warnings before expiry)
    • Role: Select Maintainer (required for webhook management)
    • Scopes: Check api (required for MR and webhook operations)
  3. Click Create project access token
  4. Copy the generated token immediately (it won't be shown again)
  5. Paste the token in the Holistics dialog

Step 3: Configure MR required or optional​

Admin can control whether Merge Requests are mandatory or optional for all changes. For detailed configuration instructions, see configure MR workflow required or optional in the main workflow documentation.

Using the MR Workflow​

Once configured, the MR workflow in GitLab works similarly to the GitHub PR workflow:

  1. Create MR: Make changes in Development, commit, and click Create MR to open GitLab
  2. Track status: Holistics displays the MR status and updates it automatically
  3. Auto-publish: When merged to master, changes publish to production automatically

For detailed usage instructions, see Using the PR/MR Workflow.

Best Practices and Additional Tips​

Customize MR templates​

Standardize your merge request process with templates:

  1. Create a directory .gitlab/merge_request_templates/ in your repository

  2. Add template files with the .md extension:

    project-root/
    └── .gitlab/
        └── merge_request_templates/
            ├── default_template.md    # Holistics uses this by default
            ├── feature.md
            └── bugfix.md

  3. Template selection behavior:

    • Holistics automatically uses default_template.md if it exists
    • If the folder contains only one template, it will be used regardless of the name
    • If there are no templates defined, Holistics will auto fill in our default template when creating merge request.

For template syntax and examples, see GitLab's template documentation.

Set up branch protection​

Protect your master branch to enforce the MR workflow:

  1. Go to Project Settings > Repository > Protected branches
  2. Configure protection for the master branch:
    • Allowed to merge: the role(s) you want (usually Maintainers)
    • Allowed to push: No one
  3. This ensures all changes must go through merge requests

Troubleshooting Common Issues​

Authentication failed​

  • Token expiration:
    • Access tokens have expiration dates. Verify that the token you are using has not expired
      • To check for personal access token expiration. In GitLab, click your Avatar → Edit profile → Access tokens. This page lists your active tokens and their expiration date
      • To check for project access token expiration. Open the Project connected to Holistics → Settings → Access tokens. Active tokens (and, on recent versions, inactive ones) are listed with their expiration date
    • If your token has expired, please create it by following the steps in this section
  • Permission levels:
    • For Project: You need the "Maintainer" role or higher
    • For Personal Access Tokens: You must have "Maintainer" access or above in the project
    • Learn more about roles and permissions on GitLab
  • Token restrictions:
    • Your GitLab administrator may have disabled Personal Access Tokens organization-wide
    • Your Group Admin might have restricted token usage at the group level
    • Check with your IT team if you suspect this is the case. Learn more

Integration Setup Issues​

  • Whitelist requirements:
  • API endpoint & port requirements (HTTPS 443 only):
    • Holistics will setup everything by calling the GitLab REST API over HTTPS on port 443 using the same domain you connected via Git. We do not use custom SSH ports for API traffic.
    • If previously you used [email protected]:2222:holistics/holistics.git to connect your repository to Holistics. Then Holistics will use this domain: https://gitlab.dev/api/v4 (HTTPS on port 443 not 2222) to make API calls

Workflow Interruptions​

Common causes and fixes:

  • Expired token: This is the most common issue

    • Solution: Follow Holistics’ guidance to generate a new token in GitLab and update it in Holistics project settings

  • Webhook template changed: Our app uses default webhook format

    • If someone modified the default webhook template, the integration will break
    • Solution: Restore the default webhook template or contact support for the correct format. Learn more

  • If a webhook fails so many times, GitLab will automatically disable it

    • Check the Recent Events in your webhook settings to see why it failed
    • Fix the underlying issue (expired token, network problem, etc.) before re-enabling
    • Re-enable the webhook only after resolving the problem (if no issues on your side, please contact our support at [email protected])
    • You'll need to manually re-enable it once the issue is fixed. Learn more about how to re-enable it
Let us know what you think about this document :)