GitHub repository connection#
A GitHub repository connection stores credentials and scope for one owner/repository pair. OakCore uses the same connection for multiple binding families that target that repo — for example GitHub Issues, GitHub pull requests, and GitHub source code.
One connection per repository#
OakCore creates one connection per scope. If you want to link multiple GitHub repositories, you need a separate connection for each one.
Note: A personal access token (PAT) on GitHub can cover multiple repositories. You may reuse the same token when creating several connections. OakCore stores it separately per connection, but scope is always one repo per connection.
Why not one connection entry with multiple repos?
- Webhooks are configured per repository on GitHub.
- Bindings verify that the artifact matches the selected connection's scope.
- Errors, permissions, and health status stay traceable per repo.
Before you start#
- Open your project in OakCore and go to Settings → Integrations.
- Add one GitHub repository connection per target repo.
- On GitHub, grant read access for the binding families you plan to use. Grant issue comment write access only if you need backlinks on issues or pull requests. Admin access is required if you want to configure webhooks.
Add a connection#
In Settings → Integrations, click Add and fill in the form.
Label#
A short name only used inside OakCore so you can tell connections apart.
| Good | Avoid |
|---|---|
Acme widgets |
acme/widgets |
Platform team backlog |
github |
Owner / Repository#
For https://github.com/acme/widgets: owner acme, repository widgets.
Artifacts you bind must belong to this exact owner/repository pair.
Personal access token (PAT)#
Stored encrypted; cannot be viewed again after you save.
Permissions are optional — configure only what you use
You do not need every scope up front. Grant only the permissions that match the binding families you use on this repo. Missing permissions for other families are fine.
| Binding family | Required token permission (fine-grained) | Classic PAT |
|---|---|---|
| Issues — read | Issues → Read | repo / public_repo |
| Issues — backlink comments | Issues → Read and write | repo / public_repo |
| Pull requests — read | Pull requests → Read | repo / public_repo |
| Pull requests — backlink comments | Pull requests → Read and write | repo / public_repo |
| Source file bindings — read | Contents → Read | repo / public_repo |
Pull request backlinks use the issue comment API (/issues/{number}/comments), but GitHub authorizes comments on pull requests through the Pull requests → Read and write permission.
Fine-grained PAT (recommended)#
- Under Repository access, select the target repo.
- Under Repository permissions, set only the rows from the table above that you need.
Classic PAT#
Scope repo (or public_repo for public repos only). Covers all families but is broader than necessary.
Webhook secret (optional)#
A shared password between GitHub and OakCore. Use the same value in OakCore and in the GitHub webhook Secret field.
openssl rand -hex 32
Test the connection#
After saving, click Test on the connection card.
The test checks whether the token can reach the configured owner/repository, then detects token permissions for supported binding families. Missing permissions appear on the connection card as Missing — for example Contents (read) without source file access.
Configure the GitHub webhook (recommended)#
Settings → Webhooks → Add webhook
| Field | Value |
|---|---|
| Payload URL | Copy from the connection card or {API_URL}/api/v1/integrations/webhooks/issue/github/{connection_id} |
| Content type | application/json |
| Secret | Same string as Webhook secret in OakCore |
| Events | See family docs below |
Which events to subscribe to
| Binding family | GitHub events |
|---|---|
| Issues | Issues (not Issue comments) |
| Pull requests | Pull requests |
| Source file bindings | No webhook needed (sync on bind and manual refresh) |
Both webhook families can share one webhook with the same payload URL.
The payload URL must use your OakCore API host, reachable from GitHub over the public internet.
Multiple repositories#
Each repository needs its own connection (its own label, optional webhook). You can reuse the same PAT across connections if the token has access to all repos.
Troubleshooting#
| Symptom | What to check |
|---|---|
| Test fails | Owner/repo typos; PAT expired; token has no access to this repo |
| Bind rejected | Artifact belongs to a different repo than the selected connection |
| Issue/PR binding fails | Missing Issues or Pull requests permission |
| Source file preview fails | Missing Contents → Read permission |
| GitHub changes not reflected | Webhook URL, secret, events, API URL reachable |
For self-hosted deployments, ensure GitHub can reach your API URL (e.g. ngrok).