Tasks into GitLab, and back

The same bridge as GitHub, for a project on GitLab — gitlab.com, or a GitLab server your team runs itself. 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 GitLab unless the developer chooses to share it.

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

Making the token

sjTasks talks to GitLab with a token you make, for this one project, with only what it needs. A project access token is best: it belongs to the project, not to a person, so it keeps working when somebody leaves.

1. In GitLab, open the project, then Settings → Access tokens, and press Add new token.
2. Give it a name you will recognise later — sjTasks — and an expiry date.
3. Set the role to Reporter. That is enough to open, label, assign and close issues.
4. Tick the api scope. Nothing else is needed.
5. Create the token and copy it. GitLab shows it once.

If your GitLab does not offer project access tokens, a personal access token with the api scope works too — made on an account that does not otherwise work the issues. Whatever the token's own account does on GitLab is taken as sjTasks talking to itself and is not brought back, so a token made on your own account means 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 GitLab card:

• GitLab address — https://gitlab.com, already filled in. If your team runs its own GitLab, put its address here instead, the one you open it at in a browser. It has to start with https:// and be reachable from the internet.
• Project — the project's path, the part after the address in the address bar: group/name, or group/subgroup/name. Pasting the whole address works too.
• Access token — the token you just made. We check it against the project 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 GitLab 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 in GitLab and it becomes a task in this project.

Press Connect. The project needs its issues switched on; GitLab has a switch for that under Settings → General → Visibility.

Letting the repository talk back

Once connected, the card shows a URL and a secret token. In GitLab, open the project's Settings → Webhooks, press Add new webhook and set:

• URL — the address from the card.
• Secret token — the secret from the card.
• Trigger — tick Issues events, and the trigger for what developers write on issues (the plain one; leave the confidential ones unticked). Untick Push events.
• SSL verification — leave it on.

Save, then use GitLab's Test button to send an issue event; GitLab shows the answer, and a 200 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.

Anything a developer marks confidential on GitLab stays there: confidential issues and internal notes are not brought back, even if the webhook is set to send them.

Sending a task to GitLab

On a task in a connected project, under the details on the right, press Send to GitLab. The task gains the send tag, an issue opens in the project, and the button gives way to a chip — Issue #57 in group/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 GitLab username behind each developer on the team. Assign a task to a person named there and the issue is assigned to their username; a developer assigning the issue to themselves puts their name on the task, and what they share arrives under their name. On GitLab this list is the only way a developer is recognised — GitLab does not send an account's email address, so it is never used. Anything from a username not on the list arrives as written on GitLab by that username. Only admins and members can stand behind a username.

What crosses, and how

Everything in Gitea's table holds here, with GitLab for Gitea. Marked done or canceled closes the issue, with a note on it saying which. An issue closed wearing wontfix or invalid cancels the task; closed any other way, the task is done.

One edit in GitLab can change several things at once — a developer relabels, retitles and reassigns and saves once. Each change follows the task, in that order.

The three status labels — status/in-progress, status/blocked, status/on-hold — are made on the project 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 GitLab has a bad minute or asks us to slow down. The Integrations page shows the last error: a token that expired or lacks the api scope or the role, a project that was renamed or moved — then connect again under its new path — or a username in Who is who that GitLab does not know. If the project 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 GitLab, and the chips on the tasks still open them. Delete the webhook in GitLab too, or it will keep knocking on a door that no longer answers.

Related

• GitHub
• Gitea
• Notes on tasks
• People, roles, and who sees what