CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/npm-semantic-release--github

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

—

Pending
Overview
Eval results
Files

plugin-lifecycle.mddocs/

Plugin Lifecycle

Core semantic-release plugin interface functions that handle the complete release workflow from validation to post-release actions. These functions implement the semantic-release plugin specification and are called automatically by semantic-release during the release process.

Capabilities

Verify Conditions

Validates GitHub authentication, repository permissions, and plugin configuration before starting the release process.

/**
 * Validates GitHub authentication and plugin configuration
 * @param pluginConfig - Plugin configuration options
 * @param context - semantic-release context with env, options, logger
 * @param options - Optional Octokit constructor override
 * @throws {AggregateError} When validation fails
 */
async function verifyConditions(
  pluginConfig: PluginConfig,
  context: Context,
  options?: { Octokit?: typeof Octokit }
): Promise<void>;

Validation Checks:

  • GitHub token presence and validity
  • Repository access permissions (push access required)
  • Configuration option validation (assets, comments, labels, etc.)
  • Repository URL format and accessibility
  • GitHub Enterprise endpoint connectivity (if configured)

Usage Example:

// Called automatically by semantic-release, but can be invoked directly
import { verifyConditions } from "@semantic-release/github";

await verifyConditions(
  {
    assets: ["dist/*.js"],
    successComment: "Released in ${nextRelease.version}",
    labels: ["semantic-release"]
  },
  {
    env: process.env,
    options: { repositoryUrl: "https://github.com/owner/repo.git" },
    logger: console
  }
);

Publish

Creates GitHub releases with optional asset uploads and discussion creation.

/**
 * Creates GitHub releases and uploads assets
 * @param pluginConfig - Plugin configuration options
 * @param context - semantic-release context with release information
 * @param options - Optional Octokit constructor override
 * @returns Release information with URL, name, ID, and discussion URL
 */
async function publish(
  pluginConfig: PluginConfig,
  context: Context,
  options?: { Octokit?: typeof Octokit }
): Promise<ReleaseResult>;

Features:

  • Creates GitHub releases with customizable names and body content
  • Uploads file assets with glob pattern support
  • Supports draft release creation
  • Creates release discussions when configured
  • Handles both prerelease and stable release types

Usage Examples:

// Simple release without assets
const result = await publish(
  {},
  {
    env: process.env,
    options: { repositoryUrl: "https://github.com/owner/repo.git" },
    branch: { name: "main" },
    nextRelease: {
      gitTag: "v1.0.0",
      name: "1.0.0",
      version: "1.0.0",
      notes: "## Changes\n- Initial release"
    },
    logger: console
  }
);
// Returns: { url: "https://github.com/owner/repo/releases/tag/v1.0.0", name: "GitHub release", id: 12345 }

// Release with assets and custom templates
const result = await publish(
  {
    assets: [
      { path: "dist/*.js", label: "JavaScript Distribution" },
      { path: "docs/*.pdf", label: "Documentation" }
    ],
    releaseNameTemplate: "${nextRelease.version} - ${nextRelease.channel || 'stable'}",
    releaseBodyTemplate: "## Release Notes\n${nextRelease.notes}\n\n## Assets\nSee attached files",
    discussionCategoryName: "Releases"
  },
  context
);

Add Channel

Updates GitHub release pre-release status for channel management in semantic-release workflows.

/**
 * Updates GitHub release pre-release status for channel management
 * @param pluginConfig - Plugin configuration options
 * @param context - semantic-release context with channel information
 * @param options - Optional Octokit constructor override
 * @returns Release information with URL and name
 */
async function addChannel(
  pluginConfig: PluginConfig,
  context: Context,
  options?: { Octokit?: typeof Octokit }
): Promise<ReleaseResult>;

Behavior:

  • Updates existing releases to change prerelease status
  • Creates new releases if none exist for the given tag
  • Manages channel-specific release metadata
  • Handles both promotion (prerelease → stable) and channel additions

Usage Example:

// Promote a prerelease to stable
const result = await addChannel(
  {},
  {
    env: process.env,
    options: { repositoryUrl: "https://github.com/owner/repo.git" },
    branch: { name: "main" },
    nextRelease: {
      gitTag: "v1.0.0",
      name: "1.0.0",
      notes: "Promoted to stable channel"
    },
    logger: console
  }
);

Success

Comments on resolved issues and PRs after successful releases, providing users with release information and closure.

/**
 * Comments on resolved issues and PRs after successful release
 * @param pluginConfig - Plugin configuration options  
 * @param context - semantic-release context with commits and release info
 * @param options - Optional Octokit constructor override
 */
async function success(
  pluginConfig: PluginConfig,
  context: Context,
  options?: { Octokit?: typeof Octokit }
): Promise<void>;

Features:

  • Comments on issues and PRs referenced in commits
  • Adds labels to resolved issues/PRs
  • Supports conditional commenting based on configuration
  • Closes previously opened failure issues
  • Handles release link generation and formatting

Usage Example:

await success(
  {
    successComment: "🎉 This issue has been resolved in version ${nextRelease.version}",
    successCommentCondition: "true", // Always comment
    releasedLabels: ["released", "v${nextRelease.version}"],
    labels: false // Don't add additional labels
  },
  {
    env: process.env,
    options: { repositoryUrl: "https://github.com/owner/repo.git" },
    commits: [
      { hash: "abc123", message: "fix: resolve issue #42" }
    ],
    nextRelease: { version: "1.0.1", gitTag: "v1.0.1" },
    releases: [{ url: "https://github.com/owner/repo/releases/tag/v1.0.1" }],
    logger: console
  }
);

Fail

Creates or updates GitHub issues when releases fail, providing detailed error information to maintainers.

/**
 * Creates or updates GitHub issues when release fails
 * @param pluginConfig - Plugin configuration options
 * @param context - semantic-release context with error information
 * @param options - Optional Octokit constructor override
 */
async function fail(
  pluginConfig: PluginConfig,
  context: Context,
  options?: { Octokit?: typeof Octokit }
): Promise<void>;

Features:

  • Creates detailed failure issues with error information
  • Updates existing failure issues with new error details
  • Supports conditional issue creation
  • Assigns issues to specified maintainers
  • Adds appropriate labels for issue categorization

Usage Example:

await fail(
  {
    failTitle: "Automated release failed 🚨",
    failComment: "The release failed with the following error:\n\n${errors[0].message}",
    failCommentCondition: "true",
    assignees: ["maintainer1", "maintainer2"],
    labels: ["bug", "release-failure"]
  },
  {
    env: process.env,
    options: { repositoryUrl: "https://github.com/owner/repo.git" },
    branch: { name: "main" },
    errors: [
      new Error("GitHub token expired")
    ],
    logger: console
  }
);

Error Handling

All plugin lifecycle functions throw AggregateError instances containing one or more SemanticReleaseError objects when validation or execution fails. Common error scenarios include:

  • Authentication Issues: Invalid or missing GitHub tokens
  • Permission Problems: Insufficient repository access rights
  • Configuration Errors: Invalid plugin configuration options
  • Network Issues: GitHub API connectivity problems
  • Rate Limiting: GitHub API rate limit exceeded
try {
  await verifyConditions(config, context);
} catch (error) {
  if (error instanceof AggregateError) {
    error.errors.forEach(err => {
      console.error(`${err.code}: ${err.message}`);
      console.error(err.details);
    });
  }
}

Install with Tessl CLI

npx tessl i tessl/npm-semantic-release--github

docs

asset-management.md

configuration.md

github-integration.md

index.md

plugin-lifecycle.md

utilities.md

tile.json