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

github-integration.mddocs/

GitHub Integration

GitHub API integration utilities providing authentication, configuration, and Octokit setup with enhanced reliability features. These utilities handle the low-level GitHub API interactions used by all plugin lifecycle functions.

Capabilities

Semantic Release Octokit

Pre-configured Octokit instance with retry, throttling, and pagination plugins for robust GitHub API interactions.

/**
 * Enhanced Octokit class with semantic-release optimizations
 * Includes retry logic, rate limiting, and pagination support
 */
class SemanticReleaseOctokit extends Octokit {
  // Inherited from Octokit with added plugins:
  // - @octokit/plugin-retry
  // - @octokit/plugin-throttling  
  // - @octokit/plugin-paginate-rest
}

Built-in Features:

  • Automatic Retries: Retries failed requests with exponential backoff
  • Rate Limit Handling: Automatically waits when rate limits are hit
  • Request Throttling: Prevents overwhelming the GitHub API
  • Pagination Support: Automatically handles paginated responses
  • Custom User Agent: Identifies requests as coming from semantic-release/github

Default Configuration:

  • Maximum 3 retries for failed requests
  • Exponential backoff starting at 1 second
  • Automatic rate limit detection and waiting
  • Custom user agent: @semantic-release/github v{version}

Usage Example:

import { SemanticReleaseOctokit } from "@semantic-release/github/lib/octokit.js";

const octokit = new SemanticReleaseOctokit({
  auth: process.env.GITHUB_TOKEN,
  baseUrl: "https://api.github.com" // Optional for GitHub Enterprise
});

// Automatic retry and rate limiting
const { data: releases } = await octokit.request("GET /repos/{owner}/{repo}/releases", {
  owner: "semantic-release",
  repo: "github"
});

// Automatic pagination
const allIssues = await octokit.paginate("GET /repos/{owner}/{repo}/issues", {
  owner: "semantic-release",
  repo: "github",
  state: "all"
});

Octokit Options Conversion

Converts plugin configuration options into Octokit constructor options with proper authentication and proxy setup.

/**
 * Converts plugin options to Octokit constructor options
 * @param options - GitHub connection and authentication options
 * @returns Octokit-compatible options object
 */
function toOctokitOptions(options: GitHubOptions): OctokitOptions;

interface GitHubOptions {
  /** GitHub personal access token or GitHub App token */
  githubToken: string;
  /** GitHub server URL (for GitHub Enterprise) */
  githubUrl?: string;
  /** API path prefix relative to githubUrl */
  githubApiPathPrefix?: string;
  /** Full GitHub API URL (overrides githubUrl + prefix) */
  githubApiUrl?: string;
  /** HTTP proxy configuration or false to disable */
  proxy?: ProxyConfig | false;
}

interface OctokitOptions {
  /** Authentication token */
  auth: string;
  /** GitHub API base URL */
  baseUrl?: string;
  /** Request configuration including proxy agent */
  request: {
    agent?: HttpProxyAgent | HttpsProxyAgent;
  };
}

interface ProxyConfig {
  /** Proxy host */
  host: string;
  /** Proxy port */
  port: number;
  /** Additional proxy headers */
  headers?: Record<string, string>;
}

URL Resolution Logic:

  1. If githubApiUrl is provided, use it directly as baseUrl
  2. If githubUrl is provided, combine with githubApiPathPrefix (default: "")
  3. Otherwise, use GitHub.com (default Octokit behavior)

Proxy Support:

  • Automatically detects HTTP vs HTTPS based on API URL protocol
  • Uses HttpProxyAgent for HTTP endpoints
  • Uses HttpsProxyAgent for HTTPS endpoints
  • Supports proxy authentication and custom headers

Usage Examples:

import { toOctokitOptions, SemanticReleaseOctokit } from "@semantic-release/github/lib/octokit.js";

// GitHub.com with proxy
const options = toOctokitOptions({
  githubToken: "ghp_xxxxxxxxxxxx",
  proxy: {
    host: "proxy.company.com",
    port: 8080,
    headers: { "Proxy-Authorization": "Basic xyz" }
  }
});

const octokit = new SemanticReleaseOctokit(options);

// GitHub Enterprise
const enterpriseOptions = toOctokitOptions({
  githubToken: "ghs_xxxxxxxxxxxx",
  githubUrl: "https://github.company.com",
  githubApiPathPrefix: "/api/v3"
});

// Direct API URL (overrides githubUrl)
const directApiOptions = toOctokitOptions({
  githubToken: "ghp_xxxxxxxxxxxx", 
  githubApiUrl: "https://api.github.company.com"
});

Authentication Methods

The plugin supports multiple GitHub authentication methods:

Personal Access Tokens:

// Environment variable
process.env.GITHUB_TOKEN = "ghp_xxxxxxxxxxxx";

// Plugin configuration
{
  "githubToken": "ghp_xxxxxxxxxxxx" // Not recommended in config files
}

GitHub App Tokens:

// Typically provided by CI systems
process.env.GITHUB_TOKEN = "ghs_xxxxxxxxxxxx";

GitHub Actions Token:

// Automatic in GitHub Actions
process.env.GITHUB_TOKEN = "${{ secrets.GITHUB_TOKEN }}";

Error Handling

GitHub integration includes comprehensive error handling for common API issues:

// Common error scenarios handled automatically:

// Rate limiting - automatically waits and retries
// HTTP 403 with rate limit headers

// Authentication errors - thrown immediately  
// HTTP 401 with invalid token

// Repository access errors - thrown immediately
// HTTP 404 for missing repo or insufficient permissions

// Network errors - retried with backoff
// Connection timeouts, DNS failures, etc.

// Server errors - retried with backoff  
// HTTP 5xx responses from GitHub

Manual Error Handling:

import { SemanticReleaseOctokit } from "@semantic-release/github/lib/octokit.js";

try {
  const octokit = new SemanticReleaseOctokit({ auth: token });
  const response = await octokit.request("GET /repos/{owner}/{repo}", {
    owner: "semantic-release",
    repo: "github"
  });
} catch (error) {
  if (error.status === 401) {
    console.error("Invalid or expired GitHub token");
  } else if (error.status === 404) {
    console.error("Repository not found or insufficient permissions");
  } else if (error.status === 403) {
    console.error("Rate limit exceeded or forbidden");
  } else {
    console.error("Unexpected GitHub API error:", error.message);
  }
}

GitHub Enterprise Support

Full support for GitHub Enterprise installations with flexible endpoint configuration:

// Method 1: Separate URL and prefix
const options = toOctokitOptions({
  githubToken: token,
  githubUrl: "https://github.company.com",
  githubApiPathPrefix: "/api/v3"
});
// Results in baseUrl: "https://github.company.com/api/v3"

// Method 2: Direct API URL
const options = toOctokitOptions({
  githubToken: token,
  githubApiUrl: "https://github-api.company.com/v3"
});
// Results in baseUrl: "https://github-api.company.com/v3"

// Environment variable support
process.env.GITHUB_URL = "https://github.company.com";
process.env.GITHUB_PREFIX = "/api/v3";
process.env.GITHUB_API_URL = "https://github-api.company.com/v3";

Performance Optimizations

The GitHub integration includes several performance optimizations:

  • Connection Pooling: Reuses HTTP connections for multiple requests
  • Request Batching: Groups related API calls when possible
  • Conditional Requests: Uses ETags and If-Modified-Since headers
  • Parallel Requests: Makes independent API calls concurrently
  • Lazy Loading: Only loads required Octokit plugins
  • Memory Management: Properly disposes of large response objects

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