github-issue-printer

Description

This tool provides the ability to print a set of issues from a GitHub repo, in a format suitable for posting on a Kanban board. The tool queries GitHub and generates a PDF with one issue per page. It is suggested to use a PDF tool capable of reducing multiple pages to a single page (example 2x2) in order to print small cards (Adobe Reader for example).

The PDF will be written to stdout - capture stdout to save it.

Usage: Input parameters

Usage of this tool requires a GitHub personal API token with repo scope. This value is supplied to the program via an environment variable named GITHUB_API_TOKEN.

Command-line parameters

$ node index.js --help

  Usage: index [options]

  Options:

    -V, --version                   output the version number
    -t, --token [github_api_token]  GitHub API token
    -o, --owner [repo_owner]        The GitHub repo owner - username or org name
    -r, --repo [repo_name]          The GitHub repo name
    -m, --milestone [number]        Repo milestone number filter (from the GitHub URL)
    -l, --labels [label_list]       Comma-separated list of labels to filter on
    -i, --issues [issue_nums]       Comma-separated list of issue numbers to include
    -p, --points                    Flag to enable the points label on cards
    --project-column                URL of a GitHub Project column from which to retrieve issues
    -h, --help                      Output usage information

Note: For security reasons, it is highly recommended to avoid passing the API token on the command line - use an environment variable instead~

Environment variables

Input parameters can be configured via the following input parameters (instead of command line arguments):

Environment Variable	Equivalent Command Line Arg
GITHUB_API_TOKEN	--token
REPO_OWNER	--owner
REPO_NAME	--repo
REPO_MILESTONE	--milestone
REPO_LABELS	--labels
REPO_ISSUES	--issues
PROJECT_COLUMN_URL	--project-column
INCLUDE_POINTS_LABELS	--points

Execution

Using Docker

You may run the program via Docker as follows:

export GITHUB_API_TOKEN=xxxxxxxxxxxxx
docker run -e GITHUB_API_TOKEN -e REPO_OWNER=<OWNER> -e REPO_NAME=<REPO> -e REPO_MILESTONE=<NUM> -e INCLUDE_POINTS_LABELS=true jamiemjennings/github-issue-printer > output.pdf

For example:

export GITHUB_API_TOKEN=xxxxxxxxxxxxx
docker run -e GITHUB_API_TOKEN -e REPO_OWNER=jamiemjennings -e REPO_NAME=github-issue-printer -e REPO_MILESTONE=1 -e INCLUDE_POINTS_LABELS=true jamiemjennings/github-issue-printer > ~/output.pdf

You may then open output.pdf with your preferred PDF reader to review/print.

Using Node

export GITHUB_API_TOKEN=xxxxxxxxxxxxx
npm install
node index.js --owner <OWNER> --repo <REPO> --milestone <NUM> --points > output.pdf

For example:

export GITHUB_API_TOKEN=xxxxxxxxxxxxx
npm install
node index.js --owner jamiemjennings --repo github-issue-printer --milestone 1 --points > output.pdf

GitHub Projects: Print Column Issues

The program may be used to print a set of issues from a column in a GitHub project. This option can expedite printing of physical Kanban cards for an existing GitHub Kanban board.

To use this option, first open the Kanban board and use the Copy column link option as shown to obtain the appropriate URL:

Then use the --project-column option with this URL, for example:

Using docker:

export GITHUB_API_TOKEN=xxxxxxxxxxxxx
docker run -e GITHUB_API_TOKEN -e PROJECT_COLUMN_URL=https://github.com/jamiemjennings/example-repo/projects/1#column-3945112 jamiemjennings/github-issue-printer > ~/output.pdf

Using node:

export GITHUB_API_TOKEN=xxxxxxxxxxxxx
npm install
node index.js --project-column https://github.com/jamiemjennings/example-repo/projects/1#column-3945112 > output.pdf

Points Labels

If you assign points to your issues as part of your development process you can add the points label to the upper right corner by using --points or setting INCLUDE_POINTS_LABELS=true. The following labels on the issue will be searched for and used if they are assigned to the issue: XS, S, M, L, XL, 0, 1/2, 1, 2, 3, 5, 8, 13, 21