GitHub Issues

Each note raised becomes an issue in one GitHub repository. Closing the issue marks the note done; reopening it opens the note again.

Before starting, do steps 1 and 2 of How connections work: data-issues="queue" on the tag, and a secret on the store.

1Make a token for Notefix

Notefix needs a fine-grained token that can only touch issues, in only this repository.

Signed in to GitHub, open github.com/settings/personal-access-tokens/new.
Token name: Notefix.
Expiration: pick a date, and put a reminder in your calendar a week before it. When a token expires, the connector stops and says so in its log.
Resource owner: the account or organisation that owns the repository.
Repository access: choose Only select repositories, and pick the repository.
Permissions: find Issues and set it to Read and write. GitHub adds Metadata: Read-only by itself. Leave everything else as it is.
Press Generate token, and copy the token. It starts with github_pat_, and GitHub will not show it again.

Note

If the repository belongs to an organisation, an owner of the organisation may have to approve the token before it works.

Careful

Do not use a classic token. A classic token with the repo scope can read and write every repository your account can see.

2Write the settings file

On the server where the store runs, make a file only you can read:

sudo mkdir -p /etc/notefix
sudo install -m 600 -o "$USER" /dev/null /etc/notefix/github.env
nano /etc/notefix/github.env

Put this in it, with your own values:

NOTEFIX_API=http://127.0.0.1:8097
NOTEFIX_BOARD=staging
NOTEFIX_SECRET=the-secret-you-gave-the-store
NOTEFIX_SITE=https://staging.acme.com
GITHUB_TOKEN=github_pat_paste-your-token
GITHUB_REPO=acme/web

Setting
`NOTEFIX_BOARD`	The same board as `data-board` on your page
`NOTEFIX_SITE`	The address people open the page at, for the link back from each issue
`GITHUB_REPO`	`owner/name`, as in the repository's address
`GITHUB_LABELS`	Optional. Labels for every issue, separated by commas: `notefix,review`

3Try it

From the unzipped download, start the connector by hand:

set -a; . /etc/notefix/github.env; set +a
python3 connectors/runner.py github

It checks the token and the repository first. When all is well it says:

github connector on board 'staging' via http://127.0.0.1:8097

Now, on your page:

Open a note and press Create an issue. It says QUEUED for a moment.
Within about 15 seconds, the note shows #1 and the issue is in your repository.
Close the issue on GitHub. Within a minute, the note turns green.

In Settings, under Connected tools, GitHub Issues now shows your repository and Working.

Stop the connector with Ctrl C, and run it as a service so it keeps going.

What the issue looks like#

Title: the first line of the note.
Body: the note's words, then who wrote it, the screen, the device and the element it points at, and a link back to the page.
For developers, folded away: the element's selector, the route and the build.
A hidden marker, so the same note is never filed twice.

GitHub has no way for programs to attach images to an issue, so screenshots stay on the note, one click away through the link.

Closed as completed or as not planned, either way the note is marked done.

If it does not work#

The connector says	What to do
`GitHub says 404 … the repo does not exist, or the token cannot see it`	Check `GITHUB_REPO`. Otherwise the token was not given this repository in step 1.5
`GitHub rejected the token`	The token was copied wrong, has expired, or was deleted. Make a new one
`Issues are turned off on …`	In the repository's Settings, under Features, turn on Issues
`GITHUB_REPO must look like owner/name`	Use the part of the address after `github.com/`, like `acme/web`
`attempt 1 failed (HTTP Error 403: Forbidden)`	`NOTEFIX_SECRET` does not match the store's `NOTES_CONNECTOR_SECRET`

See Troubleshooting for notes that stay QUEUED.