Configure GitHub

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

There is no token to create or paste. Hawzu connects through a GitHub App, so you pick the repositories on GitHub and the permissions come with the install.

Note

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

---

Before You Start

Nothing to prepare, other than permission to install a GitHub App on the organisation or account that owns your repositories. If you are not an organisation owner, GitHub will offer to send the install as a request for approval.

---

Choose what the integration does

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

• Issues — file defects as GitHub issues and keep their status in step.
• Actions — run workflows from automated test runs and import their results.

At least one is required. You can change this later from the integration’s settings; turning Actions off 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 GitHub 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 GitHub — see Defects and External Issues.

---

Connect

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

2. Search for GitHub and select it.

3. Choose the capabilities above, add a Name, and set Available to — all projects in this workspace, or selected projects.

4. Select Continue to GitHub. Hawzu opens GitHub in a new tab so you can choose which repositories it may access.

   While you are away, the page shows: “Waiting for you to finish installing on GitHub — we opened it in a new tab. This page updates on its own once you’re done.” It really does update on its own; there is nothing to paste back.

5. Choose the repositories or projects this workspace uses. See Repositories and Projects in Use.

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

If the new tab is blocked by your browser, Hawzu falls back to navigating in the current tab. Reopen GitHub restarts the step if you closed it by accident.

---

Permissions

The GitHub App requests what each capability needs. The one worth knowing about:

Actions: Read and write is required to start a workflow. Read access alone limits the integration to importing builds that someone else started.

Caution

For Hawzu to start a workflow, that workflow’s workflow_dispatch trigger must exist on the repository’s default branch — GitHub does not expose it otherwise. Hawzu warns about this when you pick the workflow.

---

After connecting

The integration shows a Connected badge with the GitHub account it is installed on, and whether it covers All repositories or Selected repositories. A Repositories in use card lists what test runs will offer, with Manage to change it.

From here you can also Configure repositories on GitHub, Reinstall on GitHub, or open Settings to change the capabilities and project scope.

If GitHub access to a repository is later withdrawn, the integration moves to Needs attention and names the repositories that went missing.

---

Self-hosted deployments

Hawzu.com users can skip this. If you run Hawzu yourself, the connect screen warns when the GitHub App is not configured. The deployment needs GITHUB_APP_ID, GITHUB_APP_SLUG, and GITHUB_APP_PRIVATE_KEY; for the authorization step it also needs GITHUB_APP_CLIENT_ID and GITHUB_APP_CLIENT_SECRET, with Request user authorization (OAuth) during installation ticked on the App itself.

---

Next Steps

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