GitHub integration

Once GitHub is connected, Multica automatically links pull requests based on issue identifiers. Issue detail shows PR state, change size, CI results, and merge conflicts in place.

The GitHub integration only reads the repositories authorized at install time; it never pushes commits, comments, or status checks.

Self-hosted Multica can also connect self-hosted Forgejo, Gitea, or GitLab instances in parallel, with the same PR auto-linking, merge-to-Done, and CI display. The entry point is Settings → Integrations → Git hosting; see Self-hosted Git hosting. Multica Cloud does not offer this entry point.

Connect GitHub

A workspace owner or admin can complete the connection:

1. Open Settings → GitHub.
2. Turn on the GitHub integration master switch.
3. Click Connect GitHub.
4. In GitHub, pick the account or organization and authorize all repositories or a chosen subset.
5. Return to Multica after the installation completes.

The connection status shows on the same page. Regular members can view the status but can't connect, disconnect, or change the switches.

Feature switches

Settings → GitHub has four switches:

Link a PR to an issue

The simplest approach is to put the issue identifier in the branch name or PR title. For example, for issue MUL-123:

mul-123-fix-login-redirect

MUL-123 Fix the redirect after login

Multica ignores case and only matches the current workspace's issue prefix. One PR can link to multiple issues.

If the identifier appears only in the PR body, use one of GitHub's close intents:

Closes MUL-123
Fixes MUL-123
Resolves MUL-123

A reference-only mention in the body, such as Related to MUL-123, is not shown as a working PR for that issue. Commit messages and PR comments don't trigger linking either.

View PRs on an issue

Once linked, PRs appear in the Pull requests block of issue detail. Each entry shows:

• repository, number, title, and author;
• Open, Draft, Merged, or Closed state;
• added and deleted lines and the number of changed files;
• CI status: all passed (with a count), some failed (naming the failing checks), or some in progress; PRs with no checks configured don't show this item — "no checks" is never treated as passing;
• mergeability: mergeable (only when GitHub reports a clean merge state), conflicting, blocked, or behind.

CI status and mergeability come from snapshots Multica pulls from the GitHub API, and the two are independent; merged or closed PRs no longer show either. When GitHub is temporarily unavailable, the card keeps the last snapshot and marks it stale instead of going blank.

Click an entry to open the PR on GitHub. Turning off the PR sidebar only hides this block; it doesn't disconnect anything.

When a merged PR moves an issue to Done

A merged PR doesn't necessarily mean the issue is finished. Multica only moves an issue to Done when all of the following hold:

1. at least one merged linked PR used a close intent immediately followed by the identifier, such as Closes MUL-123 (forms with words in between, like Closes login MUL-123, don't count);
2. the issue has no other working PR still Open or Draft (reference-only mentions in the body don't count);
3. the issue is not currently done or cancelled.

So writing MUL-123 only in the branch name or title establishes the link but doesn't by itself trigger completion. A PR closed without merging doesn't complete the issue either.

The status change is written to the timeline as a system action, and members subscribed to the issue are notified.

Multiple workspaces

The same GitHub App installation can be connected to multiple Multica workspaces. GitHub events flow into each workspace separately and are matched against each workspace's own issue prefix.

For example, a PR that references both MUL-1 and ENG-2 can link in two workspaces with different prefixes. Workspaces never see each other's issues.

Disconnect

Clicking Disconnect in Settings → GitHub only removes the relationship between the current Multica workspace and the installation; it does not uninstall the App from GitHub for you. Existing PR records are kept, and new events stop flowing into that workspace.

To revoke repository authorization on the GitHub side, uninstall the App or adjust its repository scope from your personal or organization GitHub App installations page. After uninstalling, every Multica workspace linked to that installation stops receiving events.

Self-hosting setup

Multica Cloud doesn't need this section. Self-hosting requires creating your own GitHub App first.

1. Create a GitHub App

Create the App under GitHub's Developer settings → GitHub Apps and fill in:

Repository permissions:

Subscribe to these events:

• Pull request;
• Check suite, Check run, and Status, which trigger CI and mergeability refreshes.

If you don't need CI shown in Multica, you can skip the Checks and Commit statuses permissions and their events.

2. Set environment variables

Take the slug from the App's public URL. For example, the slug of https://github.com/apps/multica-acme is multica-acme.

GITHUB_APP_SLUG=multica-acme
GITHUB_WEBHOOK_SECRET=<the webhook secret you entered when creating the App>
FRONTEND_ORIGIN=https://multica.example.com

If either GITHUB_APP_SLUG or GITHUB_WEBHOOK_SECRET is missing, the connect button is disabled and the webhook endpoint refuses to process events.

The next two variables are required for the PR card to show CI status and mergeability — Multica uses them to authenticate as the App and pull snapshots:

GITHUB_APP_ID=<the GitHub App's numeric ID>
GITHUB_APP_PRIVATE_KEY=<full PEM private key, keeping the BEGIN/END lines and newlines>

Generate the private key under the GitHub App's Private keys → Generate a private key. Without them the integration degrades gracefully: PRs still mirror, issues still auto-link and move to Done on merge — the PR card just shows no CI or merge state.

3. Update the database and connect

When upgrading an existing deployment, run the regular database migrations first:

make migrate-up

Restart the API server, then complete the connection in Settings → GitHub.

Troubleshooting

• Connect button disabled: check that GITHUB_APP_SLUG and GITHUB_WEBHOOK_SECRET reached the API process.
• Webhook returns 401: confirm the GitHub App and the API use the same webhook secret, then redeliver from GitHub's Recent Deliveries.
• PR not linked: check that the repository is in the App's authorized scope, auto-linking is on, and the identifier belongs to the current workspace.
• Identifier in the body but not shown: switch to Closes MUL-123, or put the identifier in the branch name or PR title.
• No CI status: confirm GITHUB_APP_ID and GITHUB_APP_PRIVATE_KEY are configured, and that the App has read-only Checks and Commit statuses permissions with the matching events subscribed. After adding permissions to an installed App, each installation's owner must also approve them on GitHub before they take effect.
• Issue not completed after the PR merged: confirm the PR used a close intent, and check whether other linked PRs are still Open or Draft.

Next steps

• Issues — how status transitions relate to merge-to-Done.
• Project resources — which repositories agents use when running.
• Environment variables — the full self-hosted GitHub App configuration.