tessl/npm-changelogen

Generate Beautiful Changelogs using Conventional Commits

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Overview

Eval results

Files

GitHub Integration

Name: tessl/npm-changelogen
Author: tessl

Full GitHub API integration for creating, updating, and synchronizing releases with changelog content. This module provides comprehensive GitHub release management capabilities with automatic authentication resolution and error handling.

Capabilities

Sync GitHub Release

Synchronizes a release with GitHub, creating or updating releases as needed.

/**
 * Sync release with GitHub, creating or updating as needed
 * @param config - Resolved changelog configuration with GitHub settings
 * @param release - Release information with version and body
 * @returns Result object with status and relevant URLs/IDs
 */
function syncGithubRelease(
  config: ResolvedChangelogConfig,
  release: { version: string; body: string }
): Promise<{
  status: "created" | "updated" | "manual";
  id?: string;
  url?: string;
  error?: any;
}>;

Usage Examples:

import { syncGithubRelease, loadChangelogConfig } from "changelogen";

const config = await loadChangelogConfig(process.cwd());
const release = {
  version: "1.2.0",
  body: "## Changes\n- Add new feature\n- Fix bug"
};

const result = await syncGithubRelease(config, release);

switch (result.status) {
  case "created":
    console.log(`Release created with ID: ${result.id}`);
    break;
  case "updated":
    console.log(`Release updated with ID: ${result.id}`);
    break;
  case "manual":
    console.log(`Manual action required: ${result.url}`);
    if (result.error) {
      console.error("Error:", result.error);
    }
    break;
}

Create GitHub Release

Creates a new GitHub release.

/**
 * Create a new GitHub release
 * @param config - Resolved changelog configuration with GitHub API access
 * @param body - GitHub release object with release details
 * @returns Promise resolving to created release object
 */
function createGithubRelease(
  config: ResolvedChangelogConfig,
  body: GithubRelease
): Promise<GithubRelease>;

Update GitHub Release

Updates an existing GitHub release.

/**
 * Update an existing GitHub release
 * @param config - Resolved changelog configuration with GitHub API access
 * @param id - GitHub release ID to update
 * @param body - Updated GitHub release object
 * @returns Promise resolving to updated release object
 */
function updateGithubRelease(
  config: ResolvedChangelogConfig,
  id: string,
  body: GithubRelease
): Promise<GithubRelease>;

Usage Examples:

import { 
  createGithubRelease, 
  updateGithubRelease, 
  getGithubReleaseByTag 
} from "changelogen";

// Create new release
const newRelease = await createGithubRelease(config, {
  tag_name: "v1.2.0",
  name: "v1.2.0",
  body: "Release notes here...",
  draft: false,
  prerelease: false
});

// Update existing release
const existingRelease = await getGithubReleaseByTag(config, "v1.2.0");
const updatedRelease = await updateGithubRelease(config, existingRelease.id, {
  ...existingRelease,
  body: "Updated release notes..."
});

List GitHub Releases

Retrieves all GitHub releases for the repository.

/**
 * List all GitHub releases for the repository
 * @param config - Resolved changelog configuration with repository info
 * @returns Promise resolving to array of GitHub releases
 */
function listGithubReleases(
  config: ResolvedChangelogConfig
): Promise<GithubRelease[]>;

Get GitHub Release by Tag

Retrieves a specific GitHub release by tag name.

/**
 * Get a specific GitHub release by tag name
 * @param config - Resolved changelog configuration
 * @param tag - Git tag name (e.g., "v1.2.0")
 * @returns Promise resolving to GitHub release object
 */
function getGithubReleaseByTag(
  config: ResolvedChangelogConfig,
  tag: string
): Promise<GithubRelease>;

Usage Examples:

import { 
  listGithubReleases, 
  getGithubReleaseByTag 
} from "changelogen";

// List all releases
const releases = await listGithubReleases(config);
console.log(`Found ${releases.length} releases`);

releases.forEach(release => {
  console.log(`${release.tag_name}: ${release.name}`);
});

// Get specific release
try {
  const release = await getGithubReleaseByTag(config, "v1.2.0");
  console.log(`Release v1.2.0: ${release.body}`);
} catch (error) {
  console.log("Release v1.2.0 not found");
}

Get GitHub Changelog

Retrieves the raw CHANGELOG.md file from the GitHub repository.

/**
 * Get raw CHANGELOG.md content from GitHub repository
 * @param config - Resolved changelog configuration with repository info
 * @returns Promise resolving to raw changelog content
 */
function getGithubChangelog(
  config: ResolvedChangelogConfig
): Promise<string>;

Generate Release URL

Generates a GitHub URL for manual release creation.

/**
 * Generate GitHub URL for manual release creation
 * @param config - Resolved changelog configuration
 * @param release - Release information for URL generation
 * @returns Pre-filled GitHub release creation URL
 */
function githubNewReleaseURL(
  config: ResolvedChangelogConfig,
  release: { version: string; body: string }
): string;

Usage Examples:

import { githubNewReleaseURL } from "changelogen";

const releaseUrl = githubNewReleaseURL(config, {
  version: "1.2.0",
  body: "Release notes here..."
});

console.log(`Manual release URL: ${releaseUrl}`);
// Opens pre-filled release creation form in browser

Authentication

Token Resolution

Automatic GitHub token resolution from multiple sources.

/**
 * Resolve GitHub authentication token from various sources
 * @param config - Resolved changelog configuration
 * @returns Promise resolving to GitHub token or undefined
 */
function resolveGithubToken(
  config: ResolvedChangelogConfig
): Promise<string | undefined>;

Token Sources (in order of precedence):

Environment Variables:
- CHANGELOGEN_TOKENS_GITHUB
- GITHUB_TOKEN
- GH_TOKEN
Configuration Files:
- ~/.changelogrc with tokens.github
- Project config files
GitHub CLI:
- ~/.config/gh/hosts.yml (when authenticated with gh auth login)
CLI Arguments:
- --token flag in CLI commands

Usage Examples:

import { resolveGithubToken } from "changelogen";

// Automatic token resolution
const token = await resolveGithubToken(config);
if (token) {
  console.log("GitHub token found");
  config.tokens.github = token;
} else {
  console.log("No GitHub token available - manual release required");
}

GitHub Types

interface GithubRelease {
  /** GitHub release ID (set by GitHub API) */
  id?: string;
  
  /** Git tag name for the release */
  tag_name: string;
  
  /** Display name for the release */
  name?: string;
  
  /** Markdown body content for the release */
  body?: string;
  
  /** Whether this is a draft release */
  draft?: boolean;
  
  /** Whether this is a prerelease */
  prerelease?: boolean;
}

interface GithubOptions {
  /** Repository path in format "owner/repo" */
  repo: string;
  
  /** GitHub authentication token */
  token: string;
}

GitHub Command Integration

The GitHub integration includes a dedicated command for release management:

# Sync all releases from CHANGELOG.md
npx changelogen gh release all

# Sync specific versions
npx changelogen gh release v1.2.0 v1.1.0

# Sync latest version
npx changelogen gh release

# With custom token
npx changelogen gh release --token ghp_xxxxxxxxxxxx

GitHub Release Command

/**
 * Create or update GitHub release from changelog content
 * @param config - Resolved changelog configuration
 * @param release - Release information with version and body
 * @returns Promise resolving when release sync completes
 */
function githubRelease(
  config: ResolvedChangelogConfig,
  release: { version: string; body: string }
): Promise<void>;

Error Handling and Fallbacks

Authentication Failures

When GitHub authentication fails:

Returns { status: "manual", url: "..." } from syncGithubRelease
Provides pre-filled release URL for manual creation
Optionally opens browser to release creation page

API Rate Limiting

Respects GitHub API rate limits
Provides meaningful error messages for rate limit exceeded
Suggests waiting or using authenticated requests

Repository Configuration

Validates repository configuration before API calls
Supports GitHub Enterprise instances via custom domains
Falls back to manual URLs when API unavailable

Network Errors

Graceful handling of network connectivity issues
Retries for transient failures
Clear error reporting for permanent failures

Example Error Handling:

import { syncGithubRelease } from "changelogen";

try {
  const result = await syncGithubRelease(config, release);
  
  if (result.status === "manual") {
    console.log("GitHub API unavailable - manual release required");
    console.log(`Release URL: ${result.url}`);
    
    if (result.error) {
      console.error("API Error:", result.error.message);
    }
  }
} catch (error) {
  console.error("Failed to sync release:", error.message);
}

Multi-Provider Support

While this module focuses on GitHub, the architecture supports multiple providers:

GitHub: github.com and GitHub Enterprise
GitLab: gitlab.com and self-hosted instances
Bitbucket: bitbucket.org
Custom providers: Via configuration

Repository Configuration:

interface RepoConfig {
  domain?: string;        // "github.com", "gitlab.example.com"
  repo?: string;          // "user/repository"
  provider?: RepoProvider; // "github", "gitlab", "bitbucket"
  token?: string;         // Authentication token
}

Install with Tessl CLI