Social Changelog

by Nicholas C. Zakas

If you find this useful, please consider supporting my work with a donation or nominate me for a GitHub Star.

Description

A tool that generates social media posts from GitHub releases using AI. Given a GitHub repository and release, it creates an engaging social post summarizing the key changes and improvements. This is useful for automatically creating announcement posts for new releases.

This tool uses OpenAI gpt-5.6-luna or Anthropic claude-haiku-4-5 and requires an OpenAI or Anthropic API token.

Installation

npm install @humanwhocodes/social-changelog

CLI Usage

The command line interface requires an OpenAI or Anthropic API key to be set in the environment:

export OPENAI_API_KEY=your-api-key

or

export ANTHROPIC_API_KEY=your-api-key

Note

If both OPENAI_API_KEY and ANTHROPIC_API_KEY are set, OPENAI_API_KEY takes precedence.

Note

The GitHub Models API has been retired. If you previously used GITHUB_TOKEN, please switch to using an OPENAI_API_KEY instead.

Then you can generate posts using:

npx social-changelog --org <org> --repo <repo> --name <project-name>

Options

• --org, -o - The GitHub organization or username
• --repo, -r - The repository name
• --name, -n - (Optional) The display name of the project (defaults to org/repo)
• --tag, -t - (Optional) Specific release tag to use (defaults to latest)
• --prompt-file - (Optional) Path to a file containing a custom prompt to use instead of the default
• --help, -h - Show help information

CLI Examples

Generate post for latest release:

npx social-changelog --org humanwhocodes --repo social-changelog

Use a custom prompt file:

npx social-changelog --org humanwhocodes --repo social-changelog --prompt-file ./my-prompt.txt

By default, the org/repo will be used as the project name. You can override this by providing the --name option:

npx social-changelog --org humanwhocodes --repo social-changelog --name "Social Changelog"

The latest release will be used by default. You can override this by providing the --tag option:

npx social-changelog --org humanwhocodes --repo social-changelog --name "Social Changelog" --tag v1.0.0

Note: The tag name must contain a semver-formatted version number.

The CLI outputs the post onto the console so you can capture it or pipe it into another tool.

GitHub Workflow Example

If you'd like to use Social Changelog in a GitHub Actions workflow file, you can access information directly from the actions environment to fill in the organization and repository names like this:

# Generates the social media post using OpenAI
- run: npx @humanwhocodes/social-changelog --org ${{ github.repository_owner }} --repo ${{ github.event.repository.name }} > social-post.txt
  if: ${{ steps.release.outputs.release_created }}
  env:
      OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}

API Usage

Post Generators

The library provides three post generator classes:

• ResponseAPIPostGenerator (also exported as PostGenerator for backwards compatibility) - Uses OpenAI's Responses API
• ChatCompletionPostGenerator - Uses the Chat Completions API, compatible with OpenAI and other OpenAI-compatible providers
• AnthropicPostGenerator - Uses Anthropic's Messages API, defaults to the claude-haiku-4-5 model

import {
	ResponseAPIPostGenerator,
	ChatCompletionPostGenerator,
	AnthropicPostGenerator,
} from "@humanwhocodes/social-changelog";

// Create generator instance with OpenAI API using Responses API
const openaiGenerator = new ResponseAPIPostGenerator(
	process.env.OPENAI_API_KEY,
	{
		prompt: "Optional custom prompt",
	},
);

// Or use the Chat Completions API with a custom OpenAI-compatible endpoint
const chatCompletionGenerator = new ChatCompletionPostGenerator(
	process.env.OPENAI_API_KEY,
	{
		baseUrl: "https://api.openai.com/v1/",
		model: "gpt-4o-mini",
		prompt: "Optional custom prompt",
	},
);

// Or use Anthropic's Claude models
const anthropicGenerator = new AnthropicPostGenerator(
	process.env.ANTHROPIC_API_KEY,
	{
		prompt: "Optional custom prompt",
	},
);

// Generate a post (works with any generator)
const post = await generator.generateSocialPost("Project Name", {
	url: "https://github.com/org/repo/releases/v1.0.0",
	tagName: "v1.0.0",
	version: "1.0.0",
	details: "Release notes content",
});

fetchRelease

Helper function to fetch release information from GitHub.

import { fetchRelease } from "@humanwhocodes/social-changelog";

// Fetch latest release
const release = await fetchRelease("org/repo");

// Fetch specific release
const release = await fetchRelease("org/repo", "v1.0.0");

The release object contains:

• url - Release page URL
• tagName - Git tag name
• version - Semantic version
• details - Release notes content

License

Apache 2.0