Configure GitLab

A GitLab integration can do two things, and you choose which when you connect it: file defects as GitLab issues, and run CI pipelines from automated test runs.

Note

GitLab CI used to be a separate tile on the Add Integration screen. It no longer is — one GitLab connection covers both issues and CI. Integrations connected before this change keep working.

---

Choose what the integration does

Under What should this integration do?, tick one or both:

• Issues — file defects as GitLab issues and keep their status in step.
• Pipelines — run pipelines from automated test runs and import their results.

At least one is required. Turning Pipelines off later warns you that test runs using it will report automation as unavailable until it is turned back on.

Note

With Issues on, Hawzu can create a GitLab issue as you create a defect, and you can link issues that already exist at any time. Either way the issue’s live status, priority, and assignee are shown on the defect. Changes you make in Hawzu afterwards are not pushed back to GitLab — see Defects and External Issues.

---

Where is your GitLab?

This decides how you can authenticate.

gitlab.com — you can authorize, or use a personal access token.

Self-hosted — personal access token only. Authorizing would need an OAuth application registered on your own instance, so the choice collapses to a token and Hawzu says so.

---

Connect

1. Open the workspace Integrations page and select Add Integration.

2. Search for GitLab and select it.

3. Choose the capabilities, add a name, and set the project scope.

4. Under Where is your GitLab?, choose gitlab.com or Self-hosted.

5. Choose how to authenticate, then complete the fields:

   • Authorize with GitLab (recommended) — “No token to create or paste, and the grant is scoped to Hawzu.” Select Authorize with GitLab and approve on GitLab; you are returned automatically.
   • Use a personal access token — “For a service account, or where authorizing is not an option.” Enter the Instance URL (for example https://gitlab.example.com) and an Access token beginning glpat-. The token needs the api scope.

6. Choose the projects this workspace uses. See Repositories and Projects in Use.

7. If you enabled Issues, set the project and label defaults Hawzu uses when it creates GitLab issues from defects — see Configure Issue Creation.

---

Permissions

Authorizing requests the api scope and nothing else. GitLab has no per-feature scopes, so there is no narrower grant to ask for.

Caution

The grant is not the whole story for CI. Whoever authorizes needs Developer or above on the projects you want to run pipelines in — GitLab refuses a trigger below that role, whatever the authorization allows.

Authorized tokens lapse after two hours. Hawzu refreshes them automatically, so nothing needs re-authorizing on a schedule.

---

After connecting

The integration shows an Authorized or Access token badge alongside Issues and Pipelines badges for the capabilities it has. A Projects in use card lists what test runs will offer, with Manage to change it. Re-authorize re-runs the grant if it is ever revoked on GitLab.

If access to a project is later withdrawn, the integration moves to Needs attention and names the projects that went missing.

---

Next Steps

• Repositories and Projects in Use
• Connect a CI Provider
• Defects and External Issues
• Manage Integrations