> ## Documentation Index
> Fetch the complete documentation index at: https://lunr-f6858e75.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

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

<Info>
  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.
</Info>

## Benefits of GitLab integration

<CardGroup cols={2}>
  <Card title="Merge request links" icon="code-merge">
    Automatically link commits to their associated merge requests for better traceability
  </Card>

  <Card title="Author attribution" icon="user">
    Show who contributed each change, recognizing team members and external contributors
  </Card>

  <Card title="Compare URLs" icon="link">
    Generate comparison links between versions to see all changes in GitLab's UI
  </Card>

  <Card title="Rich metadata" icon="database">
    Include MR descriptions, labels, and assignee information in your release notes
  </Card>
</CardGroup>

## Quick start

### Enable GitLab integration

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

```bash theme={}
export GITLAB_TOKEN=glpat-your_token_here

helixcommit generate --unreleased --format markdown
```

<Check>
  That's it! HelixCommit automatically detects GitLab repositories and enriches the output.
</Check>

### Disable GitLab integration

Work offline or skip MR lookups:

```bash theme={}
helixcommit generate --unreleased --no-prs --format markdown
```

## Authentication

### Creating a GitLab token

<Steps>
  <Step title="Navigate to GitLab settings">
    Go to your GitLab instance's **Settings > Access Tokens** page:

    * GitLab.com: [gitlab.com/-/user\_settings/personal\_access\_tokens](https://gitlab.com/-/user_settings/personal_access_tokens)
    * Self-hosted: `https://your-gitlab.com/-/user_settings/personal_access_tokens`

    Click **Add new token**.
  </Step>

  <Step title="Select permissions">
    <Tabs>
      <Tab title="Public projects">
        **Minimum required scope:** `read_api`

        With a token:

        * Rate limit: Higher limits than unauthenticated
        * Access to all public project data
      </Tab>

      <Tab title="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.
      </Tab>
    </Tabs>
  </Step>

  <Step title="Set the token">
    <CodeGroup>
      ```bash Environment variable (recommended) theme={}
      export GITLAB_TOKEN=glpat-your_token_here

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

      ```bash Command-line flag theme={}
      helixcommit generate \
        --unreleased \
        --gitlab-token glpat-your_token_here \
        --format markdown
      ```

      ```yaml CI/CD (GitLab CI) theme={}
      generate-release-notes:
        script:
          - helixcommit generate --unreleased --out RELEASE_NOTES.md
        variables:
          GITLAB_TOKEN: $CI_JOB_TOKEN
      ```
    </CodeGroup>

    <Warning>
      Never commit tokens to version control. Use environment variables or CI/CD secrets.
    </Warning>
  </Step>
</Steps>

## What gets enriched

### Merge request resolution

HelixCommit automatically finds MRs associated with commits:

<Tabs>
  <Tab title="Before GitLab integration">
    ```markdown theme={}
    ### Features
    - Add user authentication (abc123)
    - Implement dark mode (def456)
    ```
  </Tab>

  <Tab title="After GitLab integration">
    ```markdown theme={}
    ### 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
    ```
  </Tab>
</Tabs>

### Compare URLs

Automatic comparison links between versions:

```markdown theme={}
## 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

<Info>
  Using Conventional Commits with MR numbers in messages improves accuracy and reduces API calls.
</Info>

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

```bash theme={}
# 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:

```bash theme={}
# 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:

<Steps>
  <Step title="Respects rate limit headers">
    Reads `RateLimit-Remaining` and stops before hitting the limit.
  </Step>

  <Step title="Exponential backoff">
    Retries failed requests with increasing delays.

    ```bash theme={}
    # Configure retry behavior
    export HELIXCOMMIT_GL_MAX_RETRIES=5
    export HELIXCOMMIT_GL_BACKOFF_BASE_SEC=1.0
    export HELIXCOMMIT_GL_BACKOFF_CAP_SEC=16
    ```
  </Step>

  <Step title="Smart caching">
    Caches API responses to reduce duplicate requests.

    ```bash theme={}
    # Enable persistent caching
    export HELIXCOMMIT_GL_CACHE=1
    export HELIXCOMMIT_GL_CACHE_TTL_MINUTES=30
    ```
  </Step>
</Steps>

## Caching

### Enable GitLab API caching

Reduce API calls and improve performance:

```bash theme={}
# 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

<ResponseField name="GITLAB_TOKEN" type="string" required>
  GitLab personal access token for API authentication.

  ```bash theme={}
  export GITLAB_TOKEN=glpat-...
  ```
</ResponseField>

<ResponseField name="HELIXCOMMIT_GL_MAX_RETRIES" type="integer" default="3">
  Maximum number of retry attempts for failed API requests.

  ```bash theme={}
  export HELIXCOMMIT_GL_MAX_RETRIES=5
  ```
</ResponseField>

<ResponseField name="HELIXCOMMIT_GL_BACKOFF_BASE_SEC" type="float" default="0.5">
  Initial delay in seconds for exponential backoff.

  ```bash theme={}
  export HELIXCOMMIT_GL_BACKOFF_BASE_SEC=1.0
  ```
</ResponseField>

<ResponseField name="HELIXCOMMIT_GL_BACKOFF_CAP_SEC" type="float" default="8">
  Maximum delay in seconds between retries.

  ```bash theme={}
  export HELIXCOMMIT_GL_BACKOFF_CAP_SEC=16
  ```
</ResponseField>

<ResponseField name="HELIXCOMMIT_GL_CACHE" type="boolean" default="false">
  Enable persistent caching of GitLab API responses.

  ```bash theme={}
  export HELIXCOMMIT_GL_CACHE=1
  ```

  Valid values: `1`, `true`, `yes`, `on`
</ResponseField>

<ResponseField name="HELIXCOMMIT_GL_CACHE_DIR" type="path" default=".helixcommit-cache/gitlab">
  Directory for storing cached GitLab API responses.

  ```bash theme={}
  export HELIXCOMMIT_GL_CACHE_DIR=.cache/gl-api
  ```
</ResponseField>

<ResponseField name="HELIXCOMMIT_GL_CACHE_TTL_MINUTES" type="integer" default="10">
  Cache time-to-live in minutes.

  ```bash theme={}
  export HELIXCOMMIT_GL_CACHE_TTL_MINUTES=30
  ```
</ResponseField>

### CLI flags

<ParamField query="--gitlab-token" type="string">
  Provide GitLab token via command line.

  ```bash theme={}
  helixcommit generate --gitlab-token glpat-...
  ```

  <Warning>
    Prefer environment variables over command-line flags to avoid exposing tokens in shell history.
  </Warning>
</ParamField>

<ParamField query="--no-prs" type="boolean">
  Disable GitLab MR lookups entirely.

  ```bash theme={}
  helixcommit generate --no-prs
  ```

  Useful for:

  * Offline work
  * Faster generation when MR data isn't needed
</ParamField>

## Troubleshooting

<AccordionGroup>
  <Accordion title="API rate limit exceeded">
    If you hit rate limits:

    1. **Use authentication:**
       ```bash theme={}
       export GITLAB_TOKEN=glpat-...
       ```

    2. **Enable caching:**
       ```bash theme={}
       export HELIXCOMMIT_GL_CACHE=1
       ```

    3. **Reduce API calls:**
       ```bash theme={}
       # Use --no-prs for testing
       helixcommit generate --no-prs
       ```
  </Accordion>

  <Accordion title="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:
       ```bash theme={}
       curl --header "PRIVATE-TOKEN: $GITLAB_TOKEN" \
         "https://gitlab.com/api/v4/user"
       ```
  </Accordion>

  <Accordion title="Merge requests not found">
    If MRs aren't being linked:

    1. **Check commit messages:**
       ```bash theme={}
       git log --oneline -10
       ```
       Ensure MR numbers are mentioned: `feat: Add feature (!123)`

    2. **Verify GitLab token:**
       ```bash theme={}
       echo $GITLAB_TOKEN | cut -c1-10
       ```

    3. **Test without caching:**
       ```bash theme={}
       rm -rf .helixcommit-cache/
       helixcommit generate --unreleased
       ```

    4. **Check repository remote:**
       ```bash theme={}
       git remote get-url origin
       ```
  </Accordion>

  <Accordion title="Self-hosted GitLab not detected">
    Ensure your remote URL contains "gitlab" in the hostname:

    ```bash theme={}
    # 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
    ```
  </Accordion>
</AccordionGroup>

## GitLab CI/CD integration

### Using CI\_JOB\_TOKEN

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

```yaml theme={}
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:

```yaml theme={}
generate-release-notes:
  stage: release
  script:
    - pip install helixcommit
    - helixcommit generate --unreleased --out RELEASE_NOTES.md
  variables:
    GITLAB_TOKEN: $PROJECT_ACCESS_TOKEN
```

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

## Best practices

<AccordionGroup>
  <Accordion title="Use consistent commit message format">
    Include MR numbers in commit messages:

    ```bash theme={}
    # 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"
    ```
  </Accordion>

  <Accordion title="Enable caching in CI/CD">
    ```yaml theme={}
    # GitLab CI example
    generate-release-notes:
      cache:
        paths:
          - .helixcommit-cache/
      script:
        - export HELIXCOMMIT_GL_CACHE=1
        - helixcommit generate --unreleased --out RELEASE_NOTES.md
    ```
  </Accordion>

  <Accordion title="Test without GitLab first">
    Verify basic functionality before enabling GitLab integration:

    ```bash theme={}
    # Test offline
    helixcommit generate --unreleased --no-prs

    # Then enable GitLab
    export GITLAB_TOKEN=glpat-...
    helixcommit generate --unreleased
    ```
  </Accordion>
</AccordionGroup>

## Next steps

<CardGroup cols={2}>
  <Card title="Configuration" icon="gear" href="/configuration" color="#F6A02D">
    Configure GitLab integration settings
  </Card>

  <Card title="Examples" icon="code" href="/examples" color="#0A6ACB">
    See GitLab integration in action
  </Card>

  <Card title="CI/CD integration" icon="rotate" href="/cicd-integration" color="#F26419">
    Automate release notes in GitLab CI
  </Card>

  <Card title="Conventional Commits" icon="code-commit" href="/conventional-commits" color="#0A6ACB">
    Learn about commit message format
  </Card>
</CardGroup>