Tasks into GitHub, and back

The same bridge as Gitea, for a repository on GitHub. The client talks about the work in plain words, on the task; the developers talk about it on the issue. A person sends a task to the developers and from then on the task and the issue keep each other in step. A developer labels an issue for the client and it becomes a task here. What a developer writes on the issue stays on GitHub unless the developer chooses to share it.

A project sends its tasks to one repository. If it is connected to Gitea or GitLab, disconnect that first.

Making the token

sjTasks talks to GitHub with a token you make, for this one repository, with only the permission it needs.

1. On GitHub, open your picture in the corner, then Settings → Developer settings → Personal access tokens → Fine-grained tokens, and press Generate new token.
2. Give it a name you will recognise later — sjTasks, acme/website — and an expiry date.
3. Under Resource owner, pick the account or organisation that owns the repository. An organisation may have to allow fine-grained tokens, or approve this one, before it works.
4. Under Repository access, choose Only select repositories and pick the one repository.
5. Under Permissions → Repository permissions, set Issues to Read and write. GitHub adds Metadata: Read-only by itself. Nothing else is needed.
6. Generate the token and copy it. GitHub shows it once.

Make the token on an account that does not otherwise work on the issues — a separate account for the team's tools is best. Whatever the token's own account does on GitHub is taken as sjTasks talking to itself and is not brought back, so if you make it on your own account, closing an issue yourself will not close the task.

When the token expires, make a new one the same way and paste it in; nothing else changes.

Connecting

Open the project, press Settings, then Integrations. Only admins see this page. In the GitHub card:

• Repository — owner/name, the part after github.com/ in the address bar. Pasting the whole address works too.
• Access token — the token you just made. We check it against the repository before saving, and we keep it encrypted. The field empties after you save and never shows the token again; leave it empty later to keep the token you already gave.
• Which tag sends a task to the repository — dev unless you name another. Send to GitHub on a task puts this tag on; so does the tag picker.
• Which label brings an issue here — client unless you name another. A developer puts this label on an issue on GitHub and it becomes a task in this project.

Press Connect.

Letting the repository talk back

Once connected, the card shows a payload URL and a secret. On GitHub, open the repository's Settings → Webhooks → Add webhook and set:

• Payload URL — the address from the card.
• Content type — application/json.
• Secret — the secret from the card.
• Which events — Let me select individual events, then tick the two issue events: the issue itself (Issues), and what is written under it. Untick Pushes.

Save. GitHub sends a hello straight away; a green tick beside the webhook means the address and the secret are right. From then on the project checks every message against the secret before believing it, and a message it has already seen is not worked twice.

Sending a task to GitHub

On a task in a connected project, under the details on the right, press Send to GitHub. The task gains the send tag, an issue opens in the repository, and the button gives way to a chip — Issue #57 in owner/name — that opens it. Taking the tag off later changes nothing: the issue stays, and the two keep following each other.

Who is who

Under the connection, Who is who names the GitHub login behind each developer on the team. Assign a task to a person named there and the issue is assigned to their login; a developer assigning the issue to themselves puts their name on the task, and what they share arrives under their name. On GitHub this list is the only way a developer is recognised — an email address on a GitHub account proves nothing, so it is never used. Anything from a login not on the list arrives as written on GitHub by that login. Only admins and members can stand behind a login.

What crosses, and how

Everything in Gitea's table holds here, with GitHub for Gitea. Two things are GitHub's own:

The three status labels — status/in-progress, status/blocked, status/on-hold — are made on the repository the first time a task needs one.

How a developer answers the client

Exactly as on Gitea: begin what you write under the issue with /share, and that one becomes a note on the task, with a thumbs-up on it once it has crossed. Every issue sjTasks opens ends with the line that explains it. See Gitea.

When something goes wrong

Changes are sent in the background and retried when GitHub has a bad minute or asks us to slow down. The Integrations page shows the last error: a token that expired or lacks the Issues permission, or a repository that was renamed or moved — then connect again under its new name. If the repository refuses ten changes in a row, the connection switches itself off and says so there; fix the token and save to reconnect.

Disconnect forgets the token, the secret and the list of who is who. The issues already opened stay on GitHub, and the chips on the tasks still open them. Delete the webhook on GitHub too, or it will keep knocking on a door that no longer answers.

Related

• Gitea
• GitLab — the same bridge for a project on GitLab.
• Notes on tasks
• People, roles, and who sees what