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.
- Basic export in examples directory.
- example directory with one issue per file
- gh2md's own issues in a single file.
Default behaviour is to export all issues and PRs.
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'.
pip install gh2md. Alternatively, clone the repository and run make install.
gh2md requires a Github access token to authenticate requests. To read your
private repositories, you'll need to provide a personal access token with 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.
@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.
This has been added to the gh2md repo itself, so you can see an up-to-date
export in issues.md.