or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

cli.mdindex.md
tile.json

tessl/npm-conventional-github-releaser

Make GitHub releases from git metadata using conventional changelog conventions.

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/conventional-github-releaser@3.1.x

To install, run

npx @tessl/cli install tessl/npm-conventional-github-releaser@3.1.0

index.mddocs/

Conventional GitHub Releaser

Conventional GitHub Releaser is a Node.js library and CLI tool that automates the creation of GitHub releases from git metadata using conventional changelog conventions. It integrates with the conventional-changelog ecosystem to parse commit messages, extract meaningful information about features, fixes, performance improvements, and breaking changes, then automatically creates GitHub releases with properly formatted release notes.

Package Information

  • Package Name: conventional-github-releaser
  • Package Type: npm
  • Language: JavaScript
  • Installation: npm install conventional-github-releaser (programmatic), npm install -g conventional-github-releaser (CLI)

Core Imports

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

For ES modules:

import conventionalGithubReleaser from 'conventional-github-releaser';

Basic Usage

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

// Basic programmatic usage
conventionalGithubReleaser({
  token: 'your-github-token'  // or use environment variable CONVENTIONAL_GITHUB_RELEASER_TOKEN
}, {
  preset: 'angular'  // conventional changelog preset
}, function(err, responses) {
  if (err) {
    console.error(err);
  } else {
    console.log('Release created successfully!');
  }
});

CLI usage:

# Install globally
npm install -g conventional-github-releaser

# Create release using angular preset
conventional-github-releaser -p angular

# Generate all previous releases (first time use)
conventional-github-releaser -p angular -r 0

Architecture

Conventional GitHub Releaser is built around several key components:

  • Main API: Core conventionalGithubReleaser function providing programmatic interface
  • CLI Interface: Command-line wrapper providing user-friendly access to all functionality
  • GitHub Integration: Direct integration with GitHub API for creating releases
  • Conventional Changelog Integration: Leverages conventional-changelog for parsing commits and generating release notes
  • Transform Pipeline: Data transformation utilities for processing git metadata and formatting release content

Capabilities

GitHub Release Creation

Main function for creating GitHub releases from git metadata using conventional changelog conventions.

/**
 * Creates GitHub releases from git metadata
 * @param {Object} auth - GitHub authentication object with token and optional url
 * @param {Object} [changelogOpts] - Changelog generation options
 * @param {Object} [context] - Template context variables  
 * @param {Object} [gitRawCommitsOpts] - Git raw commits options
 * @param {Object} [parserOpts] - Parser options for commit parsing
 * @param {Object} [writerOpts] - Writer options for output formatting
 * @param {Function} callback - Callback function with signature (err, responses)
 */
function conventionalGithubReleaser(
  auth,
  changelogOpts,
  context,
  gitRawCommitsOpts,
  parserOpts,
  writerOpts,
  callback
);

CLI Interface

Data Transformation

Transform function for processing changelog data chunks, extracting version information from git tags and formatting committer dates.

/**
 * Transform function for processing changelog data chunks
 * @param {Object} chunk - Data chunk containing gitTags and committerDate properties
 * @param {Function} cb - Callback function with signature (err, transformedChunk)
 */
function transform(chunk, cb);

Configuration Types

Auth Object

interface AuthObject {
  /** GitHub Personal Token with repo scope permissions */
  token: string;
  /** GitHub API URL (defaults to 'https://api.github.com') */
  url?: string;
}

Changelog Options

interface ChangelogOptions {
  /** Conventional changelog preset (angular, atom, codemirror, ember, eslint, express, jquery, jscs, jshint) */
  preset?: string;
  /** Number of releases to generate (default: 1, 0 for all) */
  releaseCount?: number;
  /** Whether to create draft releases (default: false) */
  draft?: boolean;
  /** Release name override (defaults to version tag) */
  name?: string;
  /** Target commit/branch for release */
  targetCommitish?: string;
  /** Custom transform function */
  transform?: Function;
  /** Debug logging function */
  debug?: Function;
  /** Warning logging function */
  warn?: Function;
}

Template Context

interface TemplateContext {
  /** Repository owner */
  owner?: string;
  /** Repository name */
  repository?: string;
  /** Additional template variables */
  [key: string]: any;
}

Git Raw Commits Options

interface GitRawCommitsOptions {
  /** Starting commit/tag for changelog generation */
  from?: string;
  /** Ending commit/tag for changelog generation (defaults to latest semver tag) */
  to?: string;
  /** Additional git options */
  [key: string]: any;
}

Environment Variables

  • CONVENTIONAL_GITHUB_RELEASER_TOKEN: Default GitHub authentication token
  • CONVENTIONAL_GITHUB_URL: Default GitHub API URL (defaults to 'https://api.github.com/')
  • DEBUG: Enable debug logging by setting to 'conventional-github-releaser'

Error Handling

The library uses Node.js callback patterns for error handling:

  • Throws Error if auth object is missing
  • Throws Error if callback function is missing
  • Returns errors via callback for async operations (network failures, GitHub API errors, git command failures)
  • CLI exits with code 1 on errors and prints error messages to stderr