release-it-gitlab-mr-changelog

A release-it plugin that generates a changelog from GitLab merge requests.

Overview

This plugin fetches merged merge requests directly from GitLab API and generates a changelog based on them. It categorizes merge requests into Features, Bug Fixes, and Other Changes based on their titles and labels, and groups them between release dates. The plugin handles API errors gracefully and will generate an empty changelog if it can't fetch data from the API.

Installation

# Local installation
npm install --save-dev ./plugins/release-it-gitlab-mr-changelog

Usage

In your .release-it.js configuration file:

module.exports = {
  plugins: {
    './plugins/release-it-gitlab-mr-changelog': {
      infile: 'CHANGELOG.md'
    }
  }
};

Configuration

| Option | Type | Default | Description | |--------|------|---------|-------------| | infile | String | 'CHANGELOG.md' | The file to write the changelog to | | header | String | '# Changelog' | The header to use for the changelog file | | origin | String | Derived from repo | The base URL for GitLab |

Required Environment Variables

The plugin requires the following environment variables to be set:

| Variable | Description | Required | |----------|-------------|-------------| | GITLAB_TOKEN | Your GitLab personal access token with API access | Yes| | CI_PROJECT_ID | The ID of your GitLab project | Yes | CI_API_V4_URL | The base URL for the GitLab API (e.g., https://gitlab.example.com/api/v4) | Yes

These variables are typically available in GitLab CI/CD pipelines by default except GITLAB_TOKEN, you need to provide GITLAB_TOKEN in ci/cd pipeline variables. For local development, you can set them in your environment or in a .env file.

How It Works

1. The plugin fetches merged merge requests directly from the GitLab API using the provided environment variables.
2. It also fetches releases from the GitLab API to determine release dates.
3. It filters merge requests that were merged between the previous release date and the current release date.
4. It categorizes merge requests based on their titles and labels:
   • Features: Titles starting with "feat" or containing "feature", or with the "Feature" label
   • Bug Fixes: Titles starting with "fix" or containing "bug", or with the "Bug fix" label
   • Other Changes: All other merge requests
5. It extracts only the values inside parentheses from merge request titles (e.g., from "feat(user-auth)" it extracts "user-auth").
6. It generates a changelog with sections for each category.
7. It writes the changelog to the specified file.

Example Output

The plugin generates a changelog that looks like this:

## [1.0.0](https://gitlab.example.com/example/project/compare/v0.9.0...v1.0.0) (2025-07-31)

### Features

* user-auth ([!101](https://gitlab.example.com/project/merge_requests/101))

### Bug Fixes

* api ([!102](https://gitlab.example.com/project/merge_requests/102))

### Other Changes

* deps ([!103](https://gitlab.example.com/project/merge_requests/103))

Note that only the content inside parentheses is displayed in the changelog entries, without prefixes like "feat" or "fix".

Example Script for Testing

You can test the plugin with the following script:

// Set environment variables
process.env.GITLAB_TOKEN = 'your_gitlab_token';
process.env.CI_PROJECT_ID = 'your_project_id';
process.env.CI_API_V4_URL = 'https://gitlab.example.com/api/v4';

// Import the plugin
const GitlabMergeRequestChangelog = require('./plugins/release-it-gitlab-mr-changelog');

// Create an instance of the plugin
const plugin = new GitlabMergeRequestChangelog({
  namespace: 'gitlab-mr-changelog',
  options: {
    'gitlab-mr-changelog': {
      infile: 'CHANGELOG.md'
    }
  },
  container: {
    // Mock container with required methods
    config: {
      getContext: () => ({
        version: '1.0.0',
        tagName: 'v1.0.0',
        previousTag: 'v0.9.0',
        repo: {
          host: 'gitlab.example.com',
          repository: 'your-project'
        }
      }),
      isDryRun: false
    },
    log: {
      warn: console.warn,
      exec: console.log
    }
  }
});

// Test the plugin
async function testPlugin() {
  try {
    await plugin.init();
    const changelog = await plugin.getChangelog('0.9.0');
    console.log(changelog);
  } catch (error) {
    console.error('Error:', error);
  }
}

testPlugin();

License

MIT