or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

asset-management.mdconfiguration.mdgithub-integration.mdindex.mdplugin-lifecycle.mdutilities.md
tile.json

tessl/npm-semantic-release--github

semantic-release plugin to publish a GitHub release and comment on released Pull Requests/Issues

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/@semantic-release/github@11.0.x

To install, run

npx @tessl/cli install tessl/npm-semantic-release--github@11.0.0

index.mddocs/

@semantic-release/github

@semantic-release/github is a semantic-release plugin that integrates with GitHub's release system to automate the publishing of GitHub releases and provide intelligent commenting on pull requests and issues. It implements the complete semantic-release plugin lifecycle with GitHub-specific functionality including release creation, asset uploads, issue/PR commenting, and error handling.

Package Information

  • Package Name: @semantic-release/github
  • Package Type: npm
  • Language: JavaScript (ES modules)
  • Installation: npm install @semantic-release/github -D

Core Imports

import { verifyConditions, publish, addChannel, success, fail } from "@semantic-release/github";

For CommonJS:

const { verifyConditions, publish, addChannel, success, fail } = require("@semantic-release/github");

Basic Usage

// semantic-release configuration
{
  "plugins": [
    "@semantic-release/commit-analyzer",
    "@semantic-release/release-notes-generator",
    [
      "@semantic-release/github",
      {
        "assets": [
          { "path": "dist/asset.min.css", "label": "CSS distribution" },
          { "path": "dist/asset.min.js", "label": "JS distribution" }
        ],
        "successComment": "🎉 This issue has been resolved in version ${nextRelease.version}",
        "failTitle": "Release failed 🚨",
        "labels": ["semantic-release", "automated"],
        "assignees": ["maintainer"]
      }
    ]
  ]
}

Architecture

@semantic-release/github is built around several key components:

  • Plugin Lifecycle: Implements the five semantic-release plugin hooks (verifyConditions, publish, addChannel, success, fail)
  • GitHub Integration: Uses Octokit with retry, throttling, and pagination for robust GitHub API interactions
  • Configuration System: Flexible configuration with environment variable fallbacks and validation
  • Asset Management: Supports glob patterns and metadata for release asset uploads
  • Template System: Lodash templates for customizable comments and release content
  • Error Handling: Comprehensive error types with detailed documentation links

Capabilities

Plugin Lifecycle Functions

Core semantic-release plugin interface functions that handle the complete release workflow from validation to post-release actions.

async function verifyConditions(
  pluginConfig: PluginConfig,
  context: Context,
  options?: { Octokit?: typeof Octokit }
): Promise<void>;

async function publish(
  pluginConfig: PluginConfig,
  context: Context,
  options?: { Octokit?: typeof Octokit }
): Promise<ReleaseResult>;

async function addChannel(
  pluginConfig: PluginConfig,
  context: Context,
  options?: { Octokit?: typeof Octokit }
): Promise<ReleaseResult>;

async function success(
  pluginConfig: PluginConfig,
  context: Context,
  options?: { Octokit?: typeof Octokit }
): Promise<void>;

async function fail(
  pluginConfig: PluginConfig,
  context: Context,
  options?: { Octokit?: typeof Octokit }
): Promise<void>;

Plugin Lifecycle

GitHub Integration

GitHub API integration utilities for authentication, configuration, and Octokit setup with enhanced reliability.

class SemanticReleaseOctokit extends Octokit {
  // Pre-configured with retry, throttling, and pagination plugins
}

function toOctokitOptions(options: GitHubOptions): OctokitOptions;

interface GitHubOptions {
  githubToken: string;
  githubUrl?: string;
  githubApiPathPrefix?: string;
  githubApiUrl?: string;
  proxy?: ProxyConfig | false;
}

GitHub Integration

Configuration Management

Configuration resolution system that merges plugin options with environment variables and applies sensible defaults.

function resolveConfig(
  pluginConfig: PluginConfig,
  context: { env: NodeJS.ProcessEnv }
): ResolvedConfig;

interface PluginConfig {
  githubUrl?: string;
  githubApiUrl?: string;
  githubApiPathPrefix?: string;
  proxy?: ProxyConfig | false;
  assets?: AssetConfig[];
  successComment?: string | false;
  successCommentCondition?: string | false;
  failTitle?: string | false;
  failComment?: string | false;
  failCommentCondition?: string | false;
  labels?: string[] | false;
  assignees?: string[];
  releasedLabels?: string[] | false;
  addReleases?: "top" | "bottom" | false;
  draftRelease?: boolean;
  releaseNameTemplate?: string;
  releaseBodyTemplate?: string;
  discussionCategoryName?: string | false;
}

Configuration

Asset Management

File asset handling system supporting glob patterns, metadata, and upload management for GitHub releases.

async function globAssets(
  context: { cwd: string },
  assets: AssetConfig[]
): Promise<ResolvedAsset[]>;

type AssetConfig = string | {
  path: string | string[];
  name?: string;
  label?: string;
};

interface ResolvedAsset {
  path: string;
  name?: string;
  label?: string;
}

Asset Management

Utility Functions

Helper functions for URL parsing, templating, error handling, and GitHub-specific operations.

function parseGitHubUrl(repositoryUrl: string): { owner?: string; repo?: string };

function getSuccessComment(successComment: string, context: Context): string;

function getFailComment(failComment: string, context: Context): string;

function getReleaseLinks(releases: Release[]): string;

async function findSRIssues(
  octokit: Octokit,
  params: { owner: string; repo: string }
): Promise<Issue[]>;

function getError(code: string, context?: any): SemanticReleaseError;

Utilities

Types

interface Context {
  env: NodeJS.ProcessEnv;
  options: { repositoryUrl: string; publish?: any[] };
  branch: { name: string };
  nextRelease?: {
    gitTag: string;
    name: string;
    version: string;
    notes: string;
    channel?: string;
  };
  commits?: Commit[];
  releases?: Release[];
  logger: Logger;
}

interface ReleaseResult {
  url: string;
  name: string;
  id: number;
  discussion_url?: string;
}

interface ProxyConfig {
  host: string;
  port: number;
  headers?: Record<string, string>;
}

interface Logger {
  log(message: string, ...args: any[]): void;
  warn(message: string, ...args: any[]): void;
  error(message: string, ...args: any[]): void;
}

interface SemanticReleaseError extends Error {
  name: string;
  message: string;
  details: string;
  code: string;
}