or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

github-releaser.mdgitlab-releaser.mdindex.md
tile.json

gitlab-releaser.mddocs/

GitLab Releaser

The conventional-gitlab-releaser package creates GitLab releases from git metadata using conventional changelog patterns. It integrates with conventional-changelog to parse commit messages and generate structured release notes, supporting both GitLab.com and self-hosted GitLab instances with API v3 and v4 compatibility.

Capabilities

Release Creation

Creates GitLab releases from conventional commits with GitLab-specific features.

/**
 * Creates GitLab releases from conventional commits
 * @param {Object} auth - Authentication configuration
 * @param {string} auth.token - GitLab Personal Access Token or API token
 * @param {string} [auth.url] - GitLab instance URL, defaults to 'https://gitlab.com'
 * @param {Object} [changelogOpts] - Changelog generation options
 * @param {string} [changelogOpts.preset] - Commit convention preset (angular, atom, codemirror, ember, eslint, express, jquery, jscs, jshint)
 * @param {number} [changelogOpts.releaseCount=1] - Number of releases to generate (0 = regenerate all)
 * @param {string} [changelogOpts.config] - Path to config script file
 * @param {Object} [changelogOpts.pkg] - Package configuration
 * @param {string} [changelogOpts.pkg.path] - Path to package.json file  
 * @param {Function} [changelogOpts.debug] - Debug logging function
 * @param {Function} [changelogOpts.warn] - Warning logging function
 * @param {Object} [context] - Template context variables
 * @param {string} context.owner - GitLab namespace/user/group
 * @param {string} context.repository - GitLab project name
 * @param {Object} [gitRawCommitsOpts] - Git commit parsing options
 * @param {string} [gitRawCommitsOpts.from] - Starting commit/tag (based on releaseCount by default)
 * @param {string} [gitRawCommitsOpts.to] - Ending commit/tag (defaults to latest semver tag)
 * @param {Object} [parserOpts] - Commit message parser options
 * @param {Object} [writerOpts] - Changelog writer options
 * @param {Function} callback - Callback function (err, responses) => {}
 * @returns {void} Results returned via callback
 */
function conventionalGitlabReleaser(
  auth,
  changelogOpts,
  context,
  gitRawCommitsOpts,
  parserOpts,
  writerOpts,
  callback
);

Usage Examples:

const conventionalGitlabReleaser = require('conventional-gitlab-releaser');

// Minimal usage with required parameters
conventionalGitlabReleaser({
  token: process.env.GITLAB_TOKEN
}, {
  preset: 'angular'
}, (err, responses) => {
  if (err) throw err;
  console.log(`Created ${responses.length} releases`);
});

// Advanced usage with GitLab.com
conventionalGitlabReleaser({
  token: process.env.GITLAB_TOKEN,
  url: 'https://gitlab.com'
}, {
  preset: 'angular',
  releaseCount: 3,
  pkg: { path: './package.json' },
  debug: console.log,
  warn: console.warn
}, {
  owner: 'mygroup',
  repository: 'myproject'
}, {
  from: 'v1.0.0',
  to: 'v2.0.0'
}, null, {
  includeDetails: true,
  headerPartial: ''
}, (err, responses) => {
  if (err) {
    console.error('Release creation failed:', err);
    return;
  }
  
  responses.forEach((response, index) => {
    console.log(`Release ${index + 1}:`, response.body.web_url);
  });
});

// Self-hosted GitLab instance
conventionalGitlabReleaser({
  token: process.env.GITLAB_TOKEN,
  url: 'https://gitlab.company.com'
}, {
  preset: 'angular'
}, (err, responses) => {
  if (err) {
    console.error('Release creation failed:', err);
    return;
  }
  console.log('Successfully created releases on self-hosted GitLab');
});

Command Line Interface

Full-featured CLI providing access to all library functionality.

# Usage: conventional-gitlab-releaser [options]
# 
# Options:
#   -u, --url <url>              GitLab instance URL (default: 'https://gitlab.com')
#   -t, --token <token>          GitLab authentication token
#   -p, --preset <preset>        Commit convention preset (angular, atom, codemirror, ember, eslint, express, jquery, jscs, jshint)
#   -k, --pkg <path>             Path to package.json file
#   -r, --release-count <number> Number of releases to generate (default: 1, 0 = regenerate all)
#   -v, --verbose                Enable verbose output for debugging
#   -n, --config <path>          Path to config script file
#   -c, --context <path>         Path to context variables script

Environment Variables:

  • CONVENTIONAL_GITLAB_RELEASER_TOKEN: GitLab auth token (alternative to --token)
  • CONVENTIONAL_GITLAB_URL: GitLab URL (alternative to --url)

Usage Examples:

# Basic usage with angular preset
conventional-gitlab-releaser -p angular -t your-gitlab-token

# Generate all releases from git history
conventional-gitlab-releaser -p angular -r 0

# Verbose output for debugging
conventional-gitlab-releaser -p angular -v

# Custom package.json location
conventional-gitlab-releaser -p angular -k ./packages/my-package/package.json

# Using environment variables
export CONVENTIONAL_GITLAB_RELEASER_TOKEN="your-token"
conventional-gitlab-releaser -p angular

# Self-hosted GitLab instance
conventional-gitlab-releaser -p angular -u https://gitlab.company.com

# Using custom config file
conventional-gitlab-releaser -n ./my-config.js -c ./my-context.js

Git Commit Transform

Processes git commit chunks to extract version information and format dates (identical to GitHub releaser).

/**
 * Transforms git commit chunks for changelog processing
 * @param {Object} chunk - Git commit chunk object
 * @param {string} chunk.gitTags - Git tag information from git log
 * @param {string} chunk.committerDate - Commit date
 * @param {Function} callback - Node.js style callback (err, transformedChunk) => {}
 * @returns {void} Results returned via callback
 */
function transform(chunk, callback);

Usage Example:

const transform = require('conventional-gitlab-releaser/src/transform');

const gitChunk = {
  gitTags: ' (tag: v1.2.3, origin/master)',
  committerDate: 'June 8, 2012'
};

transform(gitChunk, (err, transformedChunk) => {
  if (err) throw err;
  
  console.log(transformedChunk.version);      // 'v1.2.3'
  console.log(transformedChunk.committerDate); // '2012-06-08'
});

Types

/**
 * GitLab authentication configuration object
 */
interface GitLabAuthConfig {
  /** GitLab Personal Access Token or API token */
  token: string;
  /** GitLab instance URL, defaults to 'https://gitlab.com' */
  url?: string;
}

/**
 * GitLab-specific changelog generation options
 */
interface GitLabChangelogOptions {
  /** Commit convention preset name */
  preset?: 'angular' | 'atom' | 'codemirror' | 'ember' | 'eslint' | 'express' | 'jquery' | 'jscs' | 'jshint';
  /** Number of releases to generate (0 = regenerate all) */
  releaseCount?: number;
  /** Path to config script file */
  config?: string;
  /** Package configuration */
  pkg?: {
    /** Path to package.json file */
    path?: string;
  };
  /** Debug logging function */
  debug?: Function;
  /** Warning logging function */
  warn?: Function;
}

/**
 * GitLab API response for release creation
 */
interface GitLabReleaseResponse {
  /** HTTP status code */
  statusCode: number;
  /** Response body containing release data */
  body: {
    /** Tag name */
    tag_name: string;
    /** Description */
    description: string;
    /** Release name */
    name: string;
    /** Created date */
    created_at: string;
    /** Release URL */
    web_url?: string;
    /** Commit SHA */
    commit?: {
      id: string;
      short_id: string;
      title: string;
      author_name: string;
      author_email: string;
      authored_date: string;
      committer_name: string;
      committer_email: string;
      committed_date: string;
      message: string;
      web_url: string;
    };
  };
}

/**
 * Callback function type for GitLab release operations
 */
type GitLabReleaseCallback = (
  err: Error | null,
  responses?: GitLabReleaseResponse[]
) => void;

Installation and Setup

NPM Package Installation

# Library usage
npm install conventional-gitlab-releaser

# Global CLI usage
npm install -g conventional-gitlab-releaser

GitLab Token Setup

The tool requires a GitLab Personal Access Token or API token with appropriate permissions:

GitLab.com

  1. Go to GitLab.com → User Settings → Access Tokens
  2. Create token with api scope for full access or read_api + read_repository + write_repository for minimal permissions
  3. Set token via environment variable or CLI flag

Self-hosted GitLab

  1. Go to your GitLab instance → User Settings → Access Tokens
  2. Create token with appropriate API permissions
  3. Ensure your GitLab instance supports API v3 or v4
# Environment variable (recommended)
export CONVENTIONAL_GITLAB_RELEASER_TOKEN="your-token-here"

# Or via CLI flag
conventional-gitlab-releaser -t your-token-here -p angular

Repository Requirements

Your repository must have:

  • Semantic version tags (e.g., v1.0.0, v1.2.3)
  • Conventional commit messages following chosen preset format
  • Proper git history with tagged releases

GitLab-specific Features

API Version Compatibility

The tool automatically detects and adapts to GitLab API versions:

  1. First attempts API v4 (GitLab 9.0+)
  2. Falls back to API v3 (GitLab 8.17 and earlier)

This ensures compatibility with both modern and legacy GitLab instances.

Self-hosted GitLab Support

Works seamlessly with self-hosted GitLab instances:

conventionalGitlabReleaser({
  token: process.env.GITLAB_TOKEN,
  url: 'https://gitlab.company.com'
}, options, callback);
# CLI
conventional-gitlab-releaser -p angular -u https://gitlab.company.com

Project Path Encoding

The tool properly handles GitLab project paths with special characters by URL-encoding namespace/project combinations:

  • mygroup/myproject → mygroup%2Fmyproject
  • user.name/project-name → user.name%2Fproject-name

Release Creation Process

GitLab releases are created by:

  1. Creating/updating repository tags via GitLab API
  2. Adding release descriptions as tag messages
  3. Linking commits to the tagged release

The release description contains the generated changelog content from conventional commits.

Error Handling

The GitLab releaser handles several types of errors:

Required Parameter Errors:

  • Throws Error('Expected an auth object') if auth parameter is missing
  • Throws Error('Expected an callback') if callback parameter is missing

Git Repository Errors:

  • Returns Error('No semver tags found') via callback if repository has no semantic version tags

GitLab API Errors:

  • Returns HTTP error responses for authentication failures (401)
  • Returns network errors for connectivity issues
  • Returns API rate limiting errors (429)
  • Returns project access errors (404)
  • Returns permission errors (403)

Configuration Errors:

  • Returns file system errors when config or context files cannot be loaded
  • Returns parsing errors for invalid configuration files

Example Error Handling:

conventionalGitlabReleaser(auth, options, (err, responses) => {
  if (err) {
    switch (err.message) {
      case 'No semver tags found':
        console.error('Repository needs semantic version tags (e.g., v1.0.0)');
        break;
      default:
        if (err.statusCode === 401) {
          console.error('Invalid GitLab token or insufficient permissions');
        } else if (err.statusCode === 403) {
          console.error('Access denied - check project permissions');
        } else if (err.statusCode === 404) {
          console.error('Project not found or access denied');
        } else if (err.statusCode === 429) {
          console.error('GitLab API rate limit exceeded');
        } else {
          console.error('Unexpected error:', err.message);
        }
    }
    return;
  }
  
  // Process successful responses
  console.log(`Successfully created ${responses.length} releases`);
});

Differences from GitHub Releaser

Features Not Available in GitLab

  • Draft releases: GitLab doesn't support draft releases
  • Target commitish: GitLab releases are always based on the tagged commit
  • Prerelease flag: GitLab doesn't have a prerelease boolean flag

GitLab-specific Advantages

  • API version compatibility: Automatically adapts to v3 and v4 APIs
  • Better namespace handling: Properly encodes complex project paths
  • Self-hosted friendly: Works with any GitLab instance without configuration changes

CLI Differences

The GitLab CLI doesn't include:

  • -d, --draft flag (not supported by GitLab)
  • Different default URL (https://gitlab.com vs https://api.github.com)
  • Different environment variable names (CONVENTIONAL_GITLAB_* vs CONVENTIONAL_GITHUB_*)