Connect GitHub
Connect GitHub to your workspace so Oxagen can ingest repository and delivery metadata and open governed pull requests, without uploading your source-code graph.
Overview
The GitHub connection lets Oxagen ingest stable provider metadata into your workspace context graph: repositories, configured refs, commits, pull requests, issues, releases, and workflow activity. An agent reads that shared metadata through governed capabilities, scoped by its role, and a rule answers each call. The exact live code graph stays local to the agent's checkout or worktree.
Oxagen holds the connection through a GitHub App. You choose which repositories the app can see. The credential stays in Oxagen, and no agent sees it.
What Oxagen reads
| Data | GitHub permission | Access ingestion uses |
|---|---|---|
| Repository, ref, commit, and changed-file metadata | Contents + Metadata | Read-only |
| Pull requests | Pull requests | Read-only |
| Issues and comments | Issues | Read-only |
| Workflow and check metadata | Actions + Checks | Read-only |
This ingestion flow reads provider metadata. Separately, the capabilities that suggest steering changes write steering records and skills to the workspace's steering repo. It does not upload source text, symbols, chunks, code embeddings, imports, or uncommitted state into the workspace graph.
What the app can change
The app asks for write access on nine repository permissions. GitHub lists them before you install, and asks you again whenever Oxagen adds one.
| GitHub permission | Access | What Oxagen does with it |
|---|---|---|
| Contents | Read and write | Writes the branch and files of each pull request Oxagen opens. |
| Pull requests | Read and write | Opens, updates, and comments on those pull requests. |
| Checks | Read and write | Posts Oxagen's own check on a pull request. |
| Commit statuses | Read and write | Reads your CI results. |
| Issues | Read and write | Reads issues, and files a run's outcome as an issue when your workspace sends outcomes to GitHub. |
| Administration | Read and write | Creates your workspace's steering repo and applies its settings. |
| Deployments | Read and write | Records each published steering version as a deployment. |
| Actions | Read and write | Reads the steering repo's environment settings. |
| Workflows | Read and write | Lets a pull request Oxagen opens change a file under .github/workflows/. |
Metadata is read-only. The app holds no organization or account permissions.
Before you start
- You need a workspace in Oxagen and permission to add connections to it.
- You need to be able to install a GitHub App on the GitHub account or organization that owns the repositories. That usually means you are an owner or admin of that GitHub organization, or it is your personal account.
Connect a repository
Run oxagen init in your project and follow its repository connection prompts. The connection APIs also support browser authorization and source setup. The current app has no Knowledge → Sources page.
Workspace connection routes are under /v1/{orgSlug}/{workspaceSlug}/. GET connections/github/status returns the authorization status. The GitHub callback at /oauth/github/callback checks the state value, which Oxagen locks so that any change shows, before storing the authorization. Use the installation and repository endpoints to choose a repository, then create_connection and set_connection_mappings to configure ingestion.
Review the GitHub App permissions when authorizing. Repository ingestion reads, and the capabilities that suggest steering changes write. What the app can change lists the write access.
What happens during the initial sync
When you connect a repository, Oxagen makes a first pass over provider records:
- It resolves the repository's actual default branch and records repository, ref, commit, pull-request, issue, and release metadata.
- It projects provider records into the workspace graph through the governed ingestion path.
- It processes larger repositories in batches. The sync runs in the background, so you can leave the page and come back.
The connection's status moves to Connected once the sync has started. You can sync again at any time from the source's settings.
Staying up to date automatically
After the initial sync, Oxagen keeps provider metadata current as the repository changes. It ingests new commits, pull requests, issues, comments, releases, and workflow events as they happen, for the activity types your workspace has chosen to ingest. You can also start a manual Re-sync at any time.
Oxagen does not derive the official repository topology from a configured protected or default ref. It also does not verify run-to-commit, artifact, test, or file claims before projecting them into shared context. Provider metadata alone does not show that a particular agent changed a file.
Managing the connection
- Add or remove repositories: change which repositories the Oxagen app can see from GitHub → Settings → Applications → Installed GitHub Apps → Oxagen → Configure. Then reconnect or re-sync in Oxagen to pick up the change.
- Re-sync: use the connection capabilities to request another sync and inspect its status.
- Disconnect: remove the source in Oxagen. To revoke the app entirely, also uninstall the Oxagen app from your GitHub account.
Security
- A GitHub App holds the connection, with permissions you review before installing.
- The same app creates your workspace's steering repo and holds its settings. Its write access reaches every repository you select.
- Each token Oxagen mints for your steering repo names that one repository and only the permissions its work needs. Only the token that applies the steering repo's settings can change settings, and only on that repo.
- Oxagen encrypts the authorization token at rest and scopes it to your organization and workspace. The token stays in Oxagen. No agent receives it.
- Oxagen sees only the repositories you select.
- Revoke the connection at any time by uninstalling the Oxagen app from GitHub, or by removing the source in Oxagen.
Troubleshooting
| Problem | What to do |
|---|---|
| "GitHub App is not configured" (HTTP 503), or authorization won't start | GITHUB_APP_SLUG, GITHUB_APP_CLIENT_ID, GITHUB_APP_CLIENT_SECRET, or GITHUB_APP_INSTALL_STATE_SECRET is absent from the deployment environment. The error names the missing one. Contact your Oxagen admin. |
| No installations appear after authorizing | Make sure you completed the Install & Authorize step on GitHub for the account that owns your repositories. |
| A repository is missing from the list | The Oxagen app cannot see it. On GitHub, open the Oxagen app's configuration and add the repository, then return to Oxagen. |
| Sync seems stuck | Large repositories take longer. If it doesn't progress, sync again from the source settings or contact support. |