gh-attach

Upload images and videos to GitHub issues, PRs, and comments — from the CLI or via MCP.

GitHub doesn't provide an official API for comment attachments on issues and pull requests. gh-attach fills this gap with multiple upload strategies, a clean CLI, and an MCP server for AI-powered workflows.

Features

Multiple upload strategies — browser session, cookie extraction, release assets (official API), repo-branch fallback
Images + videos — PNG, GIF, JPEG, SVG, WebP, MP4, MOV, and WEBM
CLI tool — works standalone or as a gh extension (gh attach)
MCP server — expose upload capabilities to AI applications via Model Context Protocol
Fully tested — unit, integration, and E2E test suites
Automated releases — semantic versioning with conventional commits

Install

For most users, install from the public npm registry — no npm authentication is required.

Standalone CLI (npm)

# Install globally from public npm
npm install -g gh-attach

Run it as gh-attach ....

Optional: GitHub Packages mirror

# Install the scoped mirror from GitHub Packages (requires GitHub Packages auth)
npm install -g @addono/gh-attach --registry=https://npm.pkg.github.com

GitHub CLI extension

gh extension install Addono/gh-attach

Run it as gh attach ....

Standalone release binary

Download the matching asset from the latest release and place it on your PATH. Release assets are published as:

gh-attach-darwin-arm64
gh-attach-darwin-amd64
gh-attach-linux-amd64
gh-attach-windows-amd64.exe

Run it as gh-attach ....

Run without installing (npx)

# Upload a file
npx -y gh-attach@latest upload ./screenshot.png --target owner/repo#42

# Start the MCP server
npx -y gh-attach@latest mcp --transport stdio

Keeping gh-attach up to date

# npm install
npm install -g gh-attach@latest

# gh extension install
gh extension upgrade Addono/gh-attach

If you run via npx, there is nothing to upgrade locally — each invocation resolves gh-attach@latest. Pin a specific version instead if you do not want the latest release:

npx -y gh-attach@<version> mcp --transport stdio

If you installed a standalone release binary, download the newest matching asset from the latest GitHub release and replace your existing gh-attach executable.

Verify the active version with gh-attach --version or gh attach --version, depending on how you installed it.

Quick Start

If you installed gh-attach as a GitHub CLI extension, replace gh-attach with gh attach in the examples below.

# Upload a file to an issue
gh-attach upload ./screenshot.png --target owner/repo#42

# Upload using the release-asset strategy (official API, works with tokens)
gh-attach upload ./diagram.png --target #42 --strategy release-asset

# Get just the URL
gh-attach upload ./img.png --target #42 --format url

# JSON output
gh-attach upload ./img.png --target #42 --format json

Videos (.mp4, .mov, .webm) are emitted as bare URLs in markdown output so GitHub can render them inline when the target upload URL supports video playback.

Authentication

Strategy 1: Browser Session (default)

gh-attach login  # Opens browser, saves session cookies

Strategy 2: Release Assets (official API)

export GITHUB_TOKEN=ghp_...  # or GH_TOKEN
gh-attach upload ./img.png --target #42 --strategy release-asset

If neither GITHUB_TOKEN nor GH_TOKEN is set, gh-attach automatically falls back to a token from the GitHub CLI (gh auth token) — so an authenticated gh auth login session is enough. The lookup order for the API token is:

GITHUB_TOKEN environment variable
GH_TOKEN environment variable
GitHub CLI stored credentials (gh auth token) — when multiple accounts are signed in, the one most likely to have access to the target repository is preferred

This applies to every code path that needs an API token (the release-asset and repo-branch strategies, in both the CLI and the MCP server).

Strategy 3: Cookie Extraction

Automatically extracts GitHub cookies from Chrome/Firefox.

Strategy 4: Repository Branch

Commits attachments to an orphan branch. Works with any token.

MCP Server

Choose the MCP command that matches how you installed gh-attach:

Install method	MCP command
Standalone npm install	`gh-attach mcp --transport stdio`
Standalone release binary	`gh-attach mcp --transport stdio`
`gh` extension	`gh attach mcp --transport stdio`
`npx`	`npx -y gh-attach@latest mcp --transport stdio`

When the MCP client supports elicitation, upload_image can prompt for a GitHub token during the same tool call and continue the upload without requiring a separate login step first.

# stdio transport (standalone install or release binary)
gh-attach mcp --transport stdio

# stdio transport (gh extension)
gh attach mcp --transport stdio

# HTTP transport
gh-attach mcp --transport http --port 3000

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

Standalone CLI or release binary

{
  "mcpServers": {
    "gh-attach": {
      "command": "gh-attach",
      "args": ["mcp", "--transport", "stdio"]
    }
  }
}

GitHub CLI extension

{
  "mcpServers": {
    "gh-attach": {
      "command": "bash",
      "args": [
        "-lc",
        "export GITHUB_TOKEN=\"$(gh auth token)\" && exec gh attach mcp --transport stdio"
      ]
    }
  }
}

This wrapper requires bash and an authenticated GitHub CLI session (gh auth login). It resolves the token at startup instead of storing it in the config file, but the token is still present in the MCP server process environment while it is running. If bash is unavailable, use the standalone CLI setup instead.

VS Code / GitHub Copilot

Add to .vscode/settings.json:

Standalone CLI or release binary

{
  "mcp": {
    "servers": {
      "gh-attach": {
        "type": "local",
        "command": "gh-attach",
        "args": ["mcp", "--transport", "stdio"],
        "tools": ["*"]
      }
    }
  }
}

GitHub CLI extension

{
  "mcp": {
    "servers": {
      "gh-attach": {
        "type": "local",
        "command": "bash",
        "args": [
          "-lc",
          "export GITHUB_TOKEN=\"$(gh auth token)\" && exec gh attach mcp --transport stdio"
        ],
        "tools": ["*"]
      }
    }
  }
}

This wrapper requires bash and an authenticated GitHub CLI session (gh auth login). It resolves the token at startup instead of storing it in the config file, but the token is still present in the MCP server process environment while it is running. If bash is unavailable, use the standalone CLI setup instead.

If you prefer npx, use command: "npx" and prepend -y, gh-attach@latest to the args array.

Configuration

gh-attach config set strategy-order "release-asset,browser-session"
gh-attach config set default-target owner/repo
gh-attach config list
gh-attach config get default-target

Config is stored at ~/.config/gh-attach/config.json (overridable via GH_ATTACH_CONFIG or XDG_CONFIG_HOME).

Environment Variables

Variable	Description
`GITHUB_TOKEN` / `GH_TOKEN`	GitHub API token for release-asset and repo-branch strategies. When unset, falls back to `gh auth token` from the GitHub CLI.
`GH_ATTACH_COOKIES`	Session cookies for browser-session strategy
`GH_ATTACH_STRATEGY`	Override default strategy selection
`GH_ATTACH_STATE_PATH`	Override session state file location
`GH_ATTACH_CONFIG`	Override config file location
`NO_COLOR`	Disable ANSI color codes in output

Exit Codes

Code	Meaning
`0`	Success
`1`	General error
`2`	Authentication error
`3`	Validation error (bad input)
`4`	Network/upload error

Programmatic Usage

import { upload, selectStrategy } from "gh-attach";

const strategy = await selectStrategy({ token: process.env.GITHUB_TOKEN });
const result = await strategy.upload({
  file: "./screenshot.png",
  target: { owner: "octocat", repo: "hello-world", issue: 42 },
});
console.log(result.url); // https://github.com/user-attachments/assets/...

Development

npm install
npm run build       # Build with tsup
npm test            # Unit + integration tests
npm run test:e2e    # E2E tests (requires secrets)
npm run typecheck   # TypeScript strict mode
npm run lint        # ESLint

Release automation

Public npm releases publish the unscoped package as gh-attach.
GitHub Packages keeps a scoped mirror at @addono/gh-attach.
GitHub Actions publishes to npm via Trusted Publishing (OIDC), so the release workflow does not need an NPM_TOKEN repository secret.
Configure npm trusted publishing for package gh-attach with:
- Organization or user: Addono
- Repository: gh-attach
- Workflow filename: release.yml
- Environment name: leave empty unless you later protect releases with a GitHub Actions environment
After the first trusted publish succeeds, npm recommends enabling Require two-factor authentication and disallow tokens in the package publishing access settings.

Branch Protection (Recommended)

For production repositories, configure the following protections on the main branch via Settings → Branches → Branch protection rules:

Setting	Value
Require a pull request before merging	✅ enabled
Require approvals	1 review
Require status checks to pass	✅ enabled
Required status checks	`Lint & Format`, `Typecheck`, `Build`, and the `Test (...)` matrix jobs you want to enforce (for example `Test (Node 22, ubuntu-latest)` and `Test (Node 24, ubuntu-latest)`)
Require branches to be up to date	✅ enabled
Require conversation resolution	✅ enabled
Require linear history	✅ enabled
Do not allow bypassing the above settings	✅ enabled

To configure via the GitHub CLI:

gh api repos/{owner}/{repo}/branches/main/protection \
  --method PUT \
  --field required_status_checks='{"strict":true,"checks":[{"context":"Lint & Format"},{"context":"Typecheck"},{"context":"Build"},{"context":"Test (Node 22, ubuntu-latest)"},{"context":"Test (Node 24, ubuntu-latest)"}]}' \
  --field enforce_admins=true \
  --field required_pull_request_reviews='{"required_approving_review_count":1}' \
  --field restrictions=null

Specifications

See openspec/specs/ for the full OpenSpec specifications:

License

MIT

Name		Name	Last commit message	Last commit date
Latest commit History 211 Commits
.github		.github
.vscode		.vscode
openspec		openspec
scripts		scripts
src		src
test		test
.dockerignore		.dockerignore
.gitignore		.gitignore
.prettierignore		.prettierignore
.releaserc.json		.releaserc.json
AGENTS.md		AGENTS.md
CHANGELOG.md		CHANGELOG.md
Dockerfile		Dockerfile
LICENSE		LICENSE
README.md		README.md
commitlint.config.js		commitlint.config.js
demo.svg		demo.svg
eslint.config.js		eslint.config.js
gh-attach		gh-attach
gh-extension		gh-extension
package-lock.json		package-lock.json
package.json		package.json
tsconfig.json		tsconfig.json
tsup.config.ts		tsup.config.ts
vitest.config.ts		vitest.config.ts

Folders and files

Latest commit

History

Repository files navigation

gh-attach

Features

Install

Standalone CLI (npm)

Optional: GitHub Packages mirror

GitHub CLI extension

Standalone release binary

Run without installing (npx)

Keeping gh-attach up to date

Quick Start

Authentication

Strategy 1: Browser Session (default)

Strategy 2: Release Assets (official API)

Strategy 3: Cookie Extraction

Strategy 4: Repository Branch

MCP Server

Claude Desktop

Standalone CLI or release binary

GitHub CLI extension

VS Code / GitHub Copilot

Standalone CLI or release binary

GitHub CLI extension

Configuration

Environment Variables

Exit Codes

Programmatic Usage

Development

Release automation

Branch Protection (Recommended)

Specifications

License

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases 27

Packages 0

Uh oh!

Uh oh!

Contributors

Uh oh!

Languages

Packages