0.0
The project is in a healthy, maintained state
A CLI tool that exports GitHub pull requests, review threads and discussion comments to Markdown for local review.
2005
2006
2007
2008
2009
2010
2011
2012
2013
2014
2015
2016
2017
2018
2019
2020
2021
2022
2023
2024
2025
2026
 Dependencies

Development

~> 6.0
~> 6.0
~> 3.0

Runtime

~> 1.0
 Project Readme

git-markdown

Gem Version Commit messages

Convert GitHub pull requests into a single Markdown file you can review locally. Useful for offline or local AI review workflows with tools like opencode, GitHub Copilot CLI, and your own scripts.

Documentation

This README and the linked repository guides describe the checked-out code. The Ethos Link project page provides the canonical public project guide, overview and resources.

Features

  • Reuse existing GitHub credentials.
  • Export PR details, threads and summaries as Markdown.
  • Filter threads by status and write to a file or stdout.
  • Use GitHub Enterprise and local credential storage with restricted permissions.

Requirements

  • Ruby 4.0+
  • Git (for remote detection)
  • GitHub credentials with access to the requested repository; classic tokens need repo scope for private repositories

Install

gem install git-markdown

Quick start

1) Setup (optional)

git-markdown setup

2) Export a PR

From inside a git repository:

git-markdown pr 123

Or specify the repo:

git-markdown pr owner/repo#123

It saves PR-{number}-{title-slug}.md in the current directory by default. For a PR titled "Fix timeout handling", the filename is PR-123-fix-timeout-handling.md. The title slug is lowercased and replaces non-alphanumeric sequences with hyphens.

Usage

# Export PR from current repository
git-markdown pr 123

# Export PR from a specific repository
git-markdown pr owner/repo#123

# Output to stdout (useful for piping)
git-markdown pr 123 --stdout | pbcopy  # macOS; on Linux use `xclip`/`wl-copy` or redirect to a file

# Save to an existing directory
mkdir -p reviews
git-markdown pr 123 --output ./reviews/

# Filter comment threads (default: unresolved)
git-markdown pr 123 --status=unresolved
git-markdown pr 123 --status=resolved
git-markdown pr 123 --status=all

# Debug output
git-markdown pr 123 --debug

# Show version
git-markdown version

Authentication

git-markdown looks for a GitHub token in this order:

  1. GITHUB_TOKEN or GH_TOKEN environment variables
  2. Git credential store (git credential fill)
  3. GitHub CLI (gh auth token)
  4. Token saved by git-markdown setup

If you see a prompt for a GitHub username or an askpass error, set GITHUB_TOKEN or GH_TOKEN in your environment to skip git credential prompts.

GitHub Enterprise

Set both API URLs. The REST API fetches PR content; GraphQL supplies review-thread resolution states:

export GITHUB_API_URL=https://github.yourcompany.com/api/v3
export GITHUB_GRAPHQL_URL=https://github.yourcompany.com/api/graphql
git-markdown pr owner/repo#123

Provide an Enterprise token through GITHUB_TOKEN or GH_TOKEN. The current Git credential lookup targets github.com, and gh auth token is invoked without an Enterprise hostname. Environment URLs fill unset configuration; values already saved in config.yml take precedence.

Output

The export contains PR metadata, descriptions and discussions. It does not include the code diff. Select comment filtering with --status; the CLI's current default is unresolved.

The generated Markdown includes:

  • PR metadata (title, author, status, created date)
  • PR description (full body)
  • Review comments grouped by file with line numbers
  • General discussion comments
  • Review summaries (approvals, change requests)

Threads marked with [resolved] or [done] are filtered out by default. Use --status=all to include them.

Configuration

Config is stored under $XDG_CONFIG_HOME/git-markdown/, or ~/.config/git-markdown/ when XDG_CONFIG_HOME is unset:

  • config.yml for provider, REST API URL and GraphQL URL settings
  • credentials for the token (permissions: 0600)

Contributing

  1. Fork it
  2. Create a branch (git checkout -b feature/my-feature)
  3. Commit your changes
  4. Push (git push origin feature/my-feature)
  5. Open a Pull Request

Please use Conventional Commits for commit messages.

Roadmap

  • GitLab Merge Request support (git-markdown mr)
  • GitLab and GitHub Issue support (git-markdown issue)
  • Custom templates
  • Optional diff in output

References

License

MIT License, see LICENSE.txt

Development and releases

Shared tooling uses published Ethos Gemkit. Keep the exact Gemfile version and workflow commit pins on the same release.

bundle install
bundle exec lefthook install
bundle exec rake verify

Release preparation, publication, registry setup and recovery are documented in the Gemkit release guide.

About Ethos Link

Ethos Link is a software company founded by Paulo Fidalgo. This gem is part of the open-source tooling we publish alongside our business products:

  • Reviato: collect private customer feedback and analyse public reviews.
  • Nuntio: prepare, review and schedule social posts.
  • EthosPlaces: find places, opening hours and contact details.

Explore our open-source projects.