gh2md

Export issues and pull requests for a Github repository to a readable markdown file. You can either create a single file for the repo, or a directory with one file per issue. See usage instructions for how to filter by issue type and state.

There are various other projects that handle Github issue exports (Eg. offline-issues), but I couldn't find one that writes all issues, comments and metadata to a single readable file.

Example exports

An example exported file is included in the examples directory. There is also an example directory with one issue per file

Default behaviour is to export all issues and PRs.

Usage

Run export for paulirish/git-open, pulling token from environment, and excluding closed PRs::

export GITHUB_ACCESS_TOKEN=myAPItoken
gh2md paulirish/git-open git-open.md --no-closed-prs

Run export for shezadkhan137/required, pulling token from file, and excluding closed issues::

echo myAPItoken > ~/.config/gh2md/token
gh2md shezadkhan137/required required.md --no-closed-issues

Run export for public repository sarabander/sicp, using no authentication and one file per issue::

   gh2md sarabander/sicp sicp-issues --multiple-files --no-closed-prs

Full help::

   usage: gh2md [-h] [--multiple-files] [-I] [--no-prs] [--no-closed-prs]
               [--no-issues] [--no-closed-issues]
               [--file-extension FILE_EXTENSION]
               repo output_path

   Export Github repository issues, pull requests and comments to markdown files:
   https://github.com/mattduck/gh2md

   Example: gh2md mattduck/gh2md my_issues.md

   Credentials are resolved in the following order:

   - A `GITHUB_ACCESS_TOKEN` environment variable.
   - An API token stored in ~/.config/gh2md/token or ~/.github-token.

   To access private repositories, you'll need a token with the full "repo" oauth
   scope.

   By default, all issues and pull requests will be fetched. You can disable these
   using the --no... flags, eg. --no-closed-prs, or --no-prs.

   positional arguments:
   repo                  Github repo to export, in format "owner/repo_name".
   output_path           Path to write exported issues.

   optional arguments:
   -h, --help            show this help message and exit
   --multiple-files      Instead of one file, treat the given path as a
                           directory, and create one file per issue, using a
                           format '{created_at}.{issue_number}.{issue_type}.{issu
                           e_state}{file_extension}'.
   -I, --idempotent      Remove non-deterministic values like timestamps. Two
                           runs of gh2md will always produce the same result, as
                           long as the Github data has not changed.
   --no-prs              Don't include pull requests in the export.
   --no-closed-prs       Don't include closed pull requests in the export.
   --no-issues           Don't include issues in the export.
   --no-closed-issues    Don't include closed issues in the export.
   --file-extension FILE_EXTENSION
                           File extension for output files. Default is '.md'.

Install

pip install gh2md. Alternatively, clone the repository and run make install.

Authentication

gh2md requires a Github access token to authenticate requests. To read your private repositories, you'll need to provide a personal access token with full the full repo oauth scope.

It's not possible to authenticate with a username and password. Github used to support this, but it was discontinued in 2020.

Github workflow: backup issues as a markdown file in your repo

@0ut0fcontrol contributed a github workflow that uses gh2md to run a nightly export to issues.md, and push it back to your repo. You can find the thread and workflow code here.