GitLab integration

Enrich release notes with GitLab merge request data and links

Overview

HelixCommit integrates with GitLab’s API to enrich your release notes with merge request information, author details, and comparison links. This integration is optional but highly recommended for repositories hosted on GitLab.

GitLab integration works with both GitLab.com and self-hosted GitLab instances. For private projects, you’ll need to provide a GitLab token with appropriate permissions.

Benefits of GitLab integration

Merge request links

Automatically link commits to their associated merge requests for better traceability

Author attribution

Show who contributed each change, recognizing team members and external contributors

Compare URLs

Generate comparison links between versions to see all changes in GitLab’s UI

Rich metadata

Include MR descriptions, labels, and assignee information in your release notes

Quick start

Enable GitLab integration

Simply set your GitLab token and HelixCommit will automatically fetch MR data:

export GITLAB_TOKEN=glpat-your_token_here

helixcommit generate --unreleased --format markdown

That’s it! HelixCommit automatically detects GitLab repositories and enriches the output.

Disable GitLab integration

Work offline or skip MR lookups:

helixcommit generate --unreleased --no-prs --format markdown

Authentication

Creating a GitLab token

1. Navigate to GitLab settings

   Go to your GitLab instance’s Settings > Access Tokens page:

   • GitLab.com: gitlab.com/-/user_settings/personal_access_tokens
   • Self-hosted: https://your-gitlab.com/-/user_settings/personal_access_tokens

   Click Add new token.

2. Select permissions

   Public projects

   Minimum required scope: read_api

   With a token:

   • Rate limit: Higher limits than unauthenticated
   • Access to all public project data

   Private projects

   Required scopes:

   • read_api - Access the API
   • read_repository - Read repository data

   For projects in private groups, ensure you have at least Reporter access.

3. Set the token

   Environment variable (recommended)

   export GITLAB_TOKEN=glpat-your_token_here
   
   # Add to your shell profile for persistence
   echo 'export GITLAB_TOKEN=glpat-your_token_here' >> ~/.bashrc
   

   Never commit tokens to version control. Use environment variables or CI/CD secrets.

What gets enriched

Merge request resolution

HelixCommit automatically finds MRs associated with commits:

Before GitLab integration

### Features
- Add user authentication (abc123)
- Implement dark mode (def456)

After GitLab integration

### Features
- Add user authentication (!42) - @johndoe
  Implements OAuth2 authentication with JWT tokens
- Implement dark mode (!45) - @janedoe
  Adds system-wide theme support with user preferences

Compare URLs

Automatic comparison links between versions:

## Release v2.0.0
_Released on 2025-11-13_

### Features
- ...

[View full changelog](https://gitlab.com/owner/repo/-/compare/v1.0.0...v2.0.0)

Commit-to-MR mapping

HelixCommit uses multiple strategies to find related MRs:

1. MR number in commit message: feat: Add feature (!123)
2. Merge commit pattern: Merge branch references
3. GitLab API lookup: Search by commit SHA

Using Conventional Commits with MR numbers in messages improves accuracy and reduces API calls.

Self-hosted GitLab

HelixCommit automatically detects self-hosted GitLab instances from your remote URL.

Configuration

The API URL is derived from your Git remote. For custom configurations:

# Your remote URL determines the GitLab instance
git remote -v
# origin  [e-mail]:group/project.git (fetch)

HelixCommit will use https://gitlab.example.com/api/v4 automatically.

Subgroups support

GitLab projects in subgroups are fully supported:

# Project path: group/subgroup/project
git remote -v
# origin  [e-mail]:group/subgroup/project.git (fetch)

Rate limiting

Understanding GitLab rate limits

Authentication	Rate limit	Notes
Unauthenticated	60 requests/hour	Per IP address
Authenticated	Higher limits	Depends on GitLab tier
CI/CD job token	Same as user	Uses job initiator’s limits

How HelixCommit handles rate limits

HelixCommit automatically manages rate limits:

1. Respects rate limit headers

   Reads RateLimit-Remaining and stops before hitting the limit.

2. Exponential backoff

   Retries failed requests with increasing delays.

   # Configure retry behavior
   export HELIXCOMMIT_GL_MAX_RETRIES=5
   export HELIXCOMMIT_GL_BACKOFF_BASE_SEC=1.0
   export HELIXCOMMIT_GL_BACKOFF_CAP_SEC=16
   
3. Smart caching

   Caches API responses to reduce duplicate requests.

   # Enable persistent caching
   export HELIXCOMMIT_GL_CACHE=1
   export HELIXCOMMIT_GL_CACHE_TTL_MINUTES=30
   

Caching

Enable GitLab API caching

Reduce API calls and improve performance:

# Enable caching
export HELIXCOMMIT_GL_CACHE=1

# Customize cache location
export HELIXCOMMIT_GL_CACHE_DIR=.cache/gitlab

# Set cache lifetime (default: 10 minutes)
export HELIXCOMMIT_GL_CACHE_TTL_MINUTES=30

# Generate with caching
helixcommit generate --unreleased

Cache structure

Cached data is stored as JSON files:

.helixcommit-cache/
└── gitlab/
    ├── mr/
    │   └── group/project/
    │       ├── 123.json      # Merge request !123
    │       └── 124.json      # Merge request !124
    └── commit_mrs/
        └── group/project/
            └── abc123.json   # Commit lookups

Configuration options

Environment variables

GITLAB_TOKEN · string · required

GitLab personal access token for API authentication.

export GITLAB_TOKEN=glpat-...

HELIXCOMMIT_GL_MAX_RETRIES · integer · default: "3"

Maximum number of retry attempts for failed API requests.

export HELIXCOMMIT_GL_MAX_RETRIES=5

HELIXCOMMIT_GL_BACKOFF_BASE_SEC · float · default: "0.5"

Initial delay in seconds for exponential backoff.

export HELIXCOMMIT_GL_BACKOFF_BASE_SEC=1.0

HELIXCOMMIT_GL_BACKOFF_CAP_SEC · float · default: "8"

Maximum delay in seconds between retries.

export HELIXCOMMIT_GL_BACKOFF_CAP_SEC=16

HELIXCOMMIT_GL_CACHE · boolean · default: "false"

Enable persistent caching of GitLab API responses.

export HELIXCOMMIT_GL_CACHE=1

Valid values: 1, true, yes, on

HELIXCOMMIT_GL_CACHE_DIR · path · default: ".helixcommit-cache/gitlab"

Directory for storing cached GitLab API responses.

export HELIXCOMMIT_GL_CACHE_DIR=.cache/gl-api

HELIXCOMMIT_GL_CACHE_TTL_MINUTES · integer · default: "10"

Cache time-to-live in minutes.

export HELIXCOMMIT_GL_CACHE_TTL_MINUTES=30

CLI flags

--gitlab-token · string

Provide GitLab token via command line.

helixcommit generate --gitlab-token glpat-...

Prefer environment variables over command-line flags to avoid exposing tokens in shell history.

--no-prs · boolean

Disable GitLab MR lookups entirely.

helixcommit generate --no-prs

Useful for:

• Offline work
• Faster generation when MR data isn’t needed

Troubleshooting

API rate limit exceeded

If you hit rate limits:

1. Use authentication:

   export GITLAB_TOKEN=glpat-...
   

2. Enable caching:

   export HELIXCOMMIT_GL_CACHE=1
   

3. Reduce API calls:

   # Use --no-prs for testing
   helixcommit generate --no-prs
   

Permission denied errors

Verify your token has correct permissions:

1. Go to your GitLab Settings > Access Tokens
2. Check token has read_api scope
3. Verify token isn’t expired
4. Test token:
   curl --header "PRIVATE-TOKEN: $GITLAB_TOKEN" \
     "https://gitlab.com/api/v4/user"
   

Merge requests not found

If MRs aren’t being linked:

1. Check commit messages:

   git log --oneline -10
   

   Ensure MR numbers are mentioned: feat: Add feature (!123)

2. Verify GitLab token:

   echo $GITLAB_TOKEN | cut -c1-10
   

3. Test without caching:

   rm -rf .helixcommit-cache/
   helixcommit generate --unreleased
   

4. Check repository remote:

   git remote get-url origin
   

Self-hosted GitLab not detected

Ensure your remote URL contains “gitlab” in the hostname:

# Works
[e-mail]:group/project.git
https://gitlab.mycompany.com/group/project.git

# May not work (no "gitlab" in hostname)
[e-mail]:group/project.git

GitLab CI/CD integration

Using CI_JOB_TOKEN

GitLab CI provides a CI_JOB_TOKEN that can be used for API access:

generate-release-notes:
  stage: release
  script:
    - pip install helixcommit
    - helixcommit generate --unreleased --out RELEASE_NOTES.md
  variables:
    GITLAB_TOKEN: $CI_JOB_TOKEN
  artifacts:
    paths:
      - RELEASE_NOTES.md

Using project access tokens

For more control, use a project access token:

generate-release-notes:
  stage: release
  script:
    - pip install helixcommit
    - helixcommit generate --unreleased --out RELEASE_NOTES.md
  variables:
    GITLAB_TOKEN: $PROJECT_ACCESS_TOKEN

Store the token in Settings > CI/CD > Variables as a masked variable.

Best practices

Use consistent commit message format

Include MR numbers in commit messages:

# Good
git commit -m "feat: Add authentication (!123)"
git commit -m "fix: Resolve rate limiting (!124)"

# Avoid (MR won't be auto-linked)
git commit -m "Add authentication"

Enable caching in CI/CD

# GitLab CI example
generate-release-notes:
  cache:
    paths:
      - .helixcommit-cache/
  script:
    - export HELIXCOMMIT_GL_CACHE=1
    - helixcommit generate --unreleased --out RELEASE_NOTES.md

Test without GitLab first

Verify basic functionality before enabling GitLab integration:

# Test offline
helixcommit generate --unreleased --no-prs

# Then enable GitLab
export GITLAB_TOKEN=glpat-...
helixcommit generate --unreleased

Next steps

Configuration

Configure GitLab integration settings

Examples

See GitLab integration in action

CI/CD integration

Automate release notes in GitLab CI

Conventional Commits

Learn about commit message format