Mark issues fixed from GitLab

Connect an app, step by step

1. In GitLab

   Make an access token

   Either kind will do:

   • A project access token (best: it reaches this one project, and is not tied to a person who might leave). In the project, go to Settings → Access tokens → Add new token.
   • A personal access token, which acts as you in every project you can reach. Choose your avatar, then Edit profile → Access tokens → Add new token.

   Name it qarunbook and set an expiry date you will remember. For a project token, choose the role Maintainer. Tick the api scope — read_api is not enough — and create the token.

   Copy it. GitLab shows it only this once. If your GitLab plan does not offer project access tokens, use a personal one.

2. In qarunbook

   Open the app's GitLab settings

   Open the app, choose App configuration, then the Integrations tab, and choose the GitLab tile under Where developers fix it.

3. In qarunbook

   Give your GitLab and the token

   Leave GitLab address as https://gitlab.com, or put in the address you open your own GitLab at. Paste the token into Access token and choose Load projects.

   The list shows only projects the token can manage. If it says That token can't manage any projects, the token needs the Maintainer role on the project.

4. In qarunbook

   Pick the project, say when a fix counts, connect

   Pick the Project. Under A fix counts, choose When its merge request merges or When it is deployed; for a deploy, fill in Environment, as GitLab names it — like production. More on both below.

   Under New issues, choose File every new issue in GitLab or Only when someone sends it. Then choose Connect.

   The card now shows the Project, when A fix counts, what happens to New issues, and the token's last four characters. qarunbook has added its webhook to the project for you — you can see it in GitLab under the project's Settings → Webhooks.

Check it works

1. In qarunbook

   Raise a test bug and copy its code

   On any check, write a line under Issues — Test: GitLab connection — and choose Add issue. The issue shows its code, like QA-14. Click the code to copy it.

   If you chose File every new issue in GitLab, it also opens in the project as [QA-14] Test: GitLab connection, and the issue here shows a GitLab #1 link.

2. In GitLab

   Merge a merge request that names it

   Open a merge request into the default branch with Fixes QA-14 in its description (or the code in its title or source branch), and merge it.

3. In qarunbook

   See it come back

   The issue now reads Fixed by [name] via GitLab · MR !1, links to the merge request, and sits under Needs retest. Whoever raised it has been told to look again. Confirm the fix, or reopen it, as usual.

   If a fix counts when it is deployed, the issue first reads MR ![number] merged, waiting for deploy, and is marked fixed once a deployment to that environment includes the change.

How it works

Every issue in qarunbook has a short code, like QA-12, shown on the issue with a button to copy it. A developer puts that code in the merge request that fixes the bug. When the merge request merges into the project's default branch, qarunbook marks the issue fixed, exactly as an admin choosing Mark fixed would: the check reads retest on the platforms it affects, the issue links to the merge request, and whoever raised it is told to look again.

Fixed is not verified. GitLab can say the code changed; only a person can say the bug is gone. The issue waits for a retest exactly as it does after any other fix.

Naming the code

Any of these marks QA-12 fixed when the merge request merges:

• In the title: Fix the cart total (QA-12)
• In the description: Fixes QA-12
• In the source branch: qa-12-cart-total

One merge request can name several codes, and fixes each of them.

When a fix counts

• When its merge request merges — into the default branch. Best when every merge goes out straight away.
• When it is deployed — once a deployment to the environment you name (as GitLab names it, like production) includes the merged change. Testers are not asked to retest a fix they cannot reach yet. GitLab records a deployment whenever a CI/CD job with an environment runs.

Issues in GitLab, too

With File every new issue in GitLab, the moment anyone raises an issue on the app it opens in the project with its code in the title and a link back. With Only when someone sends it, an admin chooses Send to GitLab on an issue to file just that one.

Closing that GitLab issue marks the qarunbook issue fixed, and so does a merge request that closes it — GitLab's own Closes #45 works as well as Fixes QA-12. GitLab does not say why an issue was closed, so every close counts.

Good to know

• Merges into branches other than the default branch are ignored until they reach it.
• GitLab receives bugs, not your test plan: checks and sections stay in qarunbook, and nothing from GitLab creates them.
• Issues raised before an app was connected get their codes when the project is saved.
• Fixing in qarunbook first is fine — a later merge that names the code changes nothing.
• The token is stored encrypted and never shown again — the card shows only its last four characters. When it expires, GitLab stops listening for qarunbook: choose Change, paste a new one and Save.
• Disconnect removes qarunbook's webhook from the project and stops merge requests marking issues fixed. Issues keep their links to GitLab. Deleting the app disconnects it too.
• On GitHub instead? Mark issues fixed from GitHub works the same way.