Configure the GitHub integration

The GitHub integration links code activity to issues: commits that mention an issue (for example #123 in the commit message, or a full issue URL) appear on that issue, and pull requests referencing an issue show as a live panel with state, review status, and checks. github.com is supported; GitHub Enterprise Server is not yet.

How authentication works

The integration uses a GitHub App that you own — created in your GitHub organization, guided by the settings page. This gives you fine-grained read-only permissions (contents, pull requests, metadata), short-lived tokens instead of stored personal access tokens, and signed webhooks. RedminePRO never gets broader access to your GitHub account than the App grants.

Setup (workspace admin, one time)

1. Go to Administration → GitHub. The page shows the exact values for creating the App — including the webhook URL and a generated webhook secret — or use the one-click manifest flow.
2. Paste the App ID and private key back into the settings page (the key is encrypted at rest and masked after saving). Use Test connection to verify.
3. Install the App on your GitHub organization and choose which repos it can see (installation link is provided on the page). Multiple organizations work with the single App: set the App to "Any account" and install it on each org — repos from all orgs appear together in the project repo picker.

Connect repos to projects (per project)

1. Enable the GitHub module for the project (Project settings → Modules).
2. Open Project settings → GitHub (requires the manage_github permission) and pick repos from those your App installation can see.
3. Mapping is many-to-many: a project can connect several repos, and one repo can feed several projects.

Issue references in commits and PRs resolve only within projects the repo is mapped to — a #123 in an unrelated repo never lands on your issue.

What appears on issues

• Commits: short SHA, first line of the message, author, branch, repo, and a link to GitHub. One commit can link to several issues.
• Pull requests: a live panel per referencing PR — open/merged/closed state, draft flag, review summary (approved / changes requested / pending), checks summary, with a refresh control.

Notes

• Events from repos not mapped to any project are dropped silently — mapping is the on/off switch.
• Smart commit keywords ("fixes #123" closing issues or logging time) and a create-branch helper are planned for a future version; commit messages today link but never change issue state.