GitLab integration - HelixCommit

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

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.

Select permissions

Public projects
Private projects

Minimum required scope: read_apiWith a token:

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

Required scopes:

read_api - Access the API
read_repository - Read repository data

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

Set the token

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
After GitLab integration

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

### 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:

MR number in commit message: feat: Add feature (!123)
Merge commit pattern: Merge branch references
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  git@gitlab.example.com: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  git@gitlab.com: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:

Respects rate limit headers

Reads RateLimit-Remaining and stops before hitting the limit.

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

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:

Use authentication:
```
export GITLAB_TOKEN=glpat-...
```
Enable caching:
```
export HELIXCOMMIT_GL_CACHE=1
```

Reduce API calls:

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

Permission denied errors

Verify your token has correct permissions:

Go to your GitLab Settings > Access Tokens
Check token has read_api scope
Verify token isn’t expired

Test token:

curl --header "PRIVATE-TOKEN: $GITLAB_TOKEN" \
  "https://gitlab.com/api/v4/user"

Merge requests not found

If MRs aren’t being linked:

Check commit messages:
```
git log --oneline -10
```
Ensure MR numbers are mentioned: feat: Add feature (!123)
Verify GitLab token:
```
echo $GITLAB_TOKEN | cut -c1-10
```

Test without caching:

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

Check repository remote:
```
git remote get-url origin
```

Self-hosted GitLab not detected

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

# Works
git@gitlab.example.com:group/project.git
https://gitlab.mycompany.com/group/project.git

# May not work (no "gitlab" in hostname)
git@code.example.com: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

Get Started

Core

Advanced

Examples

Community

​Overview

​Benefits of GitLab integration

Merge request links

Author attribution

Compare URLs

Rich metadata

​Quick start

​Enable GitLab integration

​Disable GitLab integration

​Authentication

​Creating a GitLab token

​What gets enriched

​Merge request resolution

​Compare URLs

​Commit-to-MR mapping

​Self-hosted GitLab

​Configuration

​Subgroups support

​Rate limiting

​Understanding GitLab rate limits

​How HelixCommit handles rate limits

​Caching

​Enable GitLab API caching

​Cache structure

​Configuration options

​Environment variables

​CLI flags

​Troubleshooting

​GitLab CI/CD integration

​Using CI_JOB_TOKEN

​Using project access tokens

​Best practices

​Next steps

Configuration

Examples

CI/CD integration

Conventional Commits

Overview

Benefits of GitLab integration

Quick start

Enable GitLab integration

Disable GitLab integration

Authentication

Creating a GitLab token

What gets enriched

Merge request resolution

Compare URLs

Commit-to-MR mapping

Self-hosted GitLab

Configuration

Subgroups support

Rate limiting

Understanding GitLab rate limits

How HelixCommit handles rate limits

Caching

Enable GitLab API caching

Cache structure

Configuration options

Environment variables

CLI flags

Troubleshooting

GitLab CI/CD integration

Using CI_JOB_TOKEN

Using project access tokens

Best practices

Next steps