GitHub

The shared mechanics (auto-linking by identifier, the linked-request panel, manual linking by URL, status automation, the branch-name helper, and the completion comment) are the same for both forges and are documented once in Git linking, status sync, and branch names. This page covers what is specific to GitHub: the App, connecting a workspace, and repository scope.

What it does

• Auto-links a pull request to an issue when the PR branch name or title contains an issue identifier such as PAR-123.
• Lets you link any pull request to an issue by pasting its URL, and unlink with one click. An issue can carry several linked PRs at once.
• Moves the linked issue as the PR opens, is marked ready for review, merges, or closes, following the configurable status mapping.
• Posts a completion comment back on the PR when you mark the linked issue complete in Ithura.
• Acknowledges and ignores every event other than pull_request.

Deeper issue and comment mirroring exists in the schema but is planned, not yet enabled for GitHub.

Connect (workspace admin)

Workspace settings -> Integrations -> GitHub card -> Connect GitHub. This redirects to GitHub's App install flow. On return, GitHub sends the browser to the App Setup URL, and Ithura stores the installation id for the workspace and redirects back into settings. Admin role is required to start the connect.

Repository scope

Once connected, use "Manage repos" on the GitHub card to pick which repositories are in scope for the workspace. The picker lists every repository the installation can access (fetched live using the installation token, so the SPA never holds a GitHub token) and saves your selection per workspace. Adding or removing a repository requires the Admin role.

This selection is a workspace-level record of the repositories you care about. PR linking itself does not depend on binding a repository to a project: any pull request from a repository the installation can see will link, as long as its branch or title names a live issue in the workspace. See auto-linking by identifier.

Using it

• Put an issue identifier such as PAR-123 in the PR branch name or title, and Ithura links that PR to the issue.
• Or copy a ready-made branch name from the issue (its identifier is already in the name), so the link is made the moment you push.
• To link a pull request that already exists, paste its URL on the issue.
• As the PR opens, is reviewed, merges, or closes, the linked issue follows your configured status mapping.

For the full behavior of linking, status sync, branch names, and the completion comment, see Git linking, status sync, and branch names.

GitHub Enterprise Server (self-managed)

Ithura targets github.com by default and works against a GitHub Enterprise Server instance when the API deploy is pointed at it. Setup mirrors the gitHub.com flow with three small differences:

• Base URL — set GITHUB_HOST on the API deploy (e.g. https://github.example.com). The App client rewrites its API base to ${GITHUB_HOST}/api/v3 and the install-URL prefix used by the connect flow is rewritten to the same host, so the "Connect GitHub" button opens the install page on your instance rather than github.com/apps/*.
• App registration — register the GitHub App at ${GITHUB_HOST}/settings/apps/new (organisation-wide) or under an individual account. The App ID, App Slug, private key, and webhook secret you paste back into Admin , Integrations , GitHub all live on your own instance.
• Deep sync scope — this ticket landed the connector-level slice: base URL threading, install-URL rewrite, App-token exchange against ${GITHUB_HOST}/api/v3. Deep PR sync (auto-linking, status mapping, branch-name detection) still needs a reachable GHES environment to exercise end-to-end and is deferred until an instance is available.

Reachability

Two directions matter:

1. Ithura , GHES for App token exchange, repository listing, and webhook installation. Whatever host you configure via GITHUB_HOST must be reachable from the API pod. On restricted networks, ensure the pod's outbound allowlist includes your GHES host.
2. GHES , Ithura for webhook deliveries. GHES honours an outbound-request allowlist (Settings , Security , Outbound requests) that may block deliveries to non-public hosts. If your Ithura API is at a private address, either allow the target host in that setting or expose the API behind a public reverse proxy. The webhook URL Ithura writes is derived from the API's canonical host so the card copy is honest about what URL will land.

TLS with a private CA

If GHES presents a certificate signed by a private CA, mount that CA's root into the API container's trust store (/etc/ssl/certs/) so both the token exchange and the outbound REST calls succeed.

Troubleshooting

• PRs are not linking: confirm the branch name or PR title contains the issue identifier (like PAR-123) and that the identifier names a live issue in the workspace. Repository selection does not gate linking, but the installation must be able to see the repository.
• Connect returns an error or you see "GitHub is not configured on this instance": the integration has not been enabled for your instance yet.