GitHub integration

SREDSimplify supports a project-scoped GitHub binding built on top of a user-level OAuth credential.

Endpoint map

Endpoint	Purpose
POST /api/v1/projects/{projectId}/integrations/github/oauth/start	Start GitHub OAuth and return the authorize URL
POST /api/v1/projects/{projectId}/integrations/github/oauth/exchange	Exchange the OAuth code for a stored credential
GET /api/v1/projects/{projectId}/integrations/github	Read current binding and token status
GET /api/v1/projects/{projectId}/integrations/github/repos	List accessible repositories
GET /api/v1/projects/{projectId}/integrations/github/repos/branches	List branches for a repository
POST /api/v1/projects/{projectId}/integrations/github/bind	Bind the project to a repository
DELETE /api/v1/projects/{projectId}/integrations/github	Remove the project binding

Recommended flow

1. Call /oauth/start
2. Redirect the user to authorize_url
3. Receive the GitHub callback in the frontend
4. Call /oauth/exchange with code and state
5. Call GET /integrations/github to inspect status
6. Call /repos and optionally /repos/branches
7. Call /bind with the selected repository

OAuth start

The start endpoint returns:

{
  "authorize_url": "https://github.com/login/oauth/authorize?...",
  "state": "opaque-state"
}

The backend stores OAuth state in Redis with a short TTL and validates that the callback state matches the same user and project.

OAuth exchange

Request body:

{
  "code": "github-oauth-code",
  "state": "opaque-state"
}

On success, the backend stores an encrypted credential for the user and returns the current binding status.

Binding status

Status fields:

Field	Meaning
authorized	A usable GitHub credential exists
connected	The project is currently bound to a repository
enabled	The binding is enabled for runtime use
repo_full_name	Bound repository, if connected
repo_id	GitHub repository ID
default_branch	Default branch used by the binding
token_status	Credential state
token_expires_at	Access-token expiry if known
last_refresh_at	Last refresh time if tracked

Current credential status values:

• ACTIVE
• REAUTH_REQUIRED
• REVOKED

Repository and branch discovery

GET /repos supports:

• optional query
• optional page

GET /repos/branches requires:

• repo=<owner/name>

Returned repository rows include id, full_name, default_branch, and private_repo.

Project binding

The normal binding request is:

{
  "repo_full_name": "owner/repo",
  "default_branch": "main"
}

The backend also supports a manual-token bind fallback in the request body, but the normal product flow is OAuth first, bind second.

Important behavior:

• one project can have only one active GitHub binding
• the credential is user-scoped, not project-scoped
• runtime GitHub access is attached to AI task envelopes only when the project has an enabled binding

Unbind behavior

Deleting the project binding removes the project-level association. If the credential is no longer used by any binding, the backend also removes the now-unused stored credential.