or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

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

index.mddocs/

Releaser Tools

Releaser Tools is a monorepo containing conventional release tools for creating GitHub and GitLab releases from git metadata using conventional changelog patterns. It provides both programmatic APIs and CLI tools for automating release creation based on conventional commit history.

Package Information

  • Package Name: releaser-tools
  • Package Type: npm (monorepo containing multiple packages)
  • Language: JavaScript
  • Installation: Install individual packages as needed:
    • npm install conventional-github-releaser
    • npm install conventional-gitlab-releaser
  • CLI Installation: npm install -g conventional-github-releaser conventional-gitlab-releaser

Core Imports

For GitHub releases:

const conventionalGithubReleaser = require('conventional-github-releaser');

For GitLab releases:

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

Basic Usage

GitHub Release Creation

const conventionalGithubReleaser = require('conventional-github-releaser');

conventionalGithubReleaser({
  token: 'your-github-token',
  url: 'https://api.github.com'
}, {
  preset: 'angular',
  releaseCount: 1
}, (err, responses) => {
  if (err) {
    console.error('Failed to create release:', err);
    return;
  }
  console.log('Successfully created releases:', responses);
});

GitLab Release Creation

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

conventionalGitlabReleaser({
  token: 'your-gitlab-token',
  url: 'https://gitlab.com'
}, {
  preset: 'angular',
  releaseCount: 1
}, (err, responses) => {
  if (err) {
    console.error('Failed to create release:', err);
    return;
  }
  console.log('Successfully created releases:', responses);
});

CLI Usage

# GitHub releases
export CONVENTIONAL_GITHUB_RELEASER_TOKEN="your-github-token"
conventional-github-releaser -p angular

# GitLab releases  
export CONVENTIONAL_GITLAB_RELEASER_TOKEN="your-gitlab-token"
conventional-gitlab-releaser -p angular -u https://gitlab.com

Architecture

The releaser-tools monorepo is structured around two main packages that share common functionality:

  • conventional-github-releaser: Creates GitHub releases via GitHub API
  • conventional-gitlab-releaser: Creates GitLab releases via GitLab API

Common Components

Both tools share the same architecture pattern:

  1. Main Library: Core release function that orchestrates the release creation process
  2. Transform Module: Utility for processing git commit chunks to extract version information and format dates
  3. CLI Interface: Command-line wrapper providing access to all library functionality

Workflow

The release workflow is identical for both platforms:

  1. Extract semver tags from git repository using git-semver-tags
  2. Generate changelog content using conventional-changelog
  3. Process commits through transform pipeline to extract version information
  4. Create releases via respective platform APIs (GitHub or GitLab)

Dependencies

Both packages depend on:

  • conventional-changelog: For generating structured changelogs
  • git-semver-tags: For extracting semantic version tags from git
  • dateformat: For date formatting in transform operations
  • semver-regex: For parsing semantic versions from git tags
  • through2: For stream processing
  • q: For promise handling
  • Platform-specific HTTP clients (gh-got for GitHub, gl-got for GitLab)

Capabilities

GitHub Release Creation

Create GitHub releases from conventional commits with full customization options.

function conventionalGithubReleaser(
  auth,
  changelogOpts,
  context,
  gitRawCommitsOpts,
  parserOpts,
  writerOpts,
  callback
);

GitHub Releaser

GitLab Release Creation

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

function conventionalGitlabReleaser(
  auth,
  changelogOpts,
  context,
  gitRawCommitsOpts,
  parserOpts,
  writerOpts,
  callback
);

GitLab Releaser

Git Commit Transform

Shared utility for processing git commit chunks to extract version information and format dates.

function transform(chunk, callback);

Both packages include identical transform functionality for processing git commit data:

  • Extract semantic versions from git tags using regex matching
  • Format commit dates to ISO format (YYYY-MM-DD)
  • Process git log chunks for changelog generation

Usage Example:

const transform = require('conventional-github-releaser/src/transform');
// or
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

/**
 * Authentication configuration object
 */
interface AuthConfig {
  /** Platform auth token (GitHub PAT or GitLab token) */
  token: string;
  /** Platform API URL */
  url?: string; // defaults to 'https://api.github.com' for GitHub, 'https://gitlab.com' for GitLab
}

/**
 * Changelog generation options
 */
interface ChangelogOptions {
  /** Commit convention preset name */
  preset?: 'angular' | 'atom' | 'codemirror' | 'ember' | 'eslint' | 'express' | 'jquery' | 'jscs' | 'jshint';
  /** Number of releases to generate (0 = regenerate all) */
  releaseCount?: number;
  /** Create draft releases instead of published (GitHub only) */
  draft?: boolean;
  /** Custom name for the release (defaults to version tag) */
  name?: string;
  /** Specific target_commitish for release (GitHub only) */
  targetCommitish?: string;
  /** Custom transform function for processing commits */
  transform?: Function;
  /** Package configuration */
  pkg?: {
    /** Path to package.json file */
    path?: string;
  };
  /** Debug logging function */
  debug?: Function;
  /** Warning logging function */
  warn?: Function;
}

/**
 * Template context variables
 */
interface TemplateContext {
  /** Repository owner */
  owner: string;
  /** Repository name */
  repository: string;
}

/**
 * Git commit parsing options
 */
interface GitRawCommitsOptions {
  /** Starting commit/tag for range */
  from?: string;
  /** Ending commit/tag for range */
  to?: string;
}

/**
 * Git commit chunk processed by transform
 */
interface GitCommitChunk {
  /** Git tag information from git log */
  gitTags?: string;
  /** Commit date */
  committerDate?: string;
  /** Extracted semantic version (added by transform) */
  version?: string;
}

/**
 * Platform API response for release creation
 */
interface ReleaseResponse {
  /** HTTP status code */
  statusCode: number;
  /** Response body containing release data */
  body: {
    /** Release ID */
    id: number;
    /** Release URL */
    html_url?: string; // GitHub
    web_url?: string;  // GitLab
    /** Release tag name */
    tag_name: string;
    /** Release name */
    name: string;
    /** Release body/description */
    body?: string;
    description?: string; // GitLab
    /** Whether release is a draft (GitHub only) */
    draft?: boolean;
    /** Whether release is a prerelease */
    prerelease?: boolean;
  };
}

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

/**
 * Transform callback function type
 */
type TransformCallback = (
  err: Error | null,
  chunk?: GitCommitChunk
) => void;

Error Handling

Both tools handle similar error conditions:

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

Platform API Errors:

  • Returns HTTP error responses for authentication failures (401)
  • Returns network errors for connectivity issues
  • Returns API rate limiting errors (403)

Configuration Errors:

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

Conventional Commit Presets

Both tools support the same conventional commit presets:

  • angular: Angular commit convention (default)
  • atom: Atom editor commit convention
  • codemirror: CodeMirror commit convention
  • ember: Ember.js commit convention
  • eslint: ESLint commit convention
  • express: Express.js commit convention
  • jquery: jQuery commit convention
  • jscs: JSCS commit convention
  • jshint: JSHint commit convention

Each preset defines specific commit message parsing rules and changelog formatting templates optimized for that project's workflow.