GitHub

GitHub App installation, repositories and stack detection.

Operation	Method and path
URL to install the Guv GitHub App	`GET /v1/workspaces/{workspace}/github/install-url`
Connect an installation after the GitHub redirect	`POST /v1/github/installations`
List connected GitHub installations	`GET /v1/workspaces/{workspace}/github/installations`
List repositories the installation can see	`GET /v1/workspaces/{workspace}/github/installations/{installation_id}/repositories`
Detect the stack of a repository and suggest a guv.yaml	`POST /v1/workspaces/{workspace}/github/detect`
GitHub App webhook receiver	`POST /v1/integrations/github/webhook`

URL to install the Guv GitHub App

GET /v1/workspaces/{workspace}/github/install-url

Operation: getGitHubInstallUrl
Scopes: projects:write

Parameters

Name	In	Type	Description
`workspace` *	path	string	Workspace id (`ws_…`) or slug.

Responses

Status	Meaning	Body
`200` OK	OK.	GitHubInstallUrl

Errors: 400, 401, 403, 404, 429, 500, as problem+json with a stable code.

Example

curl https://api.guv.dev/v1/workspaces/acme/github/install-url \
  -H "Authorization: Bearer $GUV_TOKEN"

Example response

{
  "url": "https://guv.dev/",
  "state": "string",
  "expires_at": "2026-10-22T13:05:00Z"
}

Connect an installation after the GitHub redirect

POST /v1/github/installations

Operation: connectGitHubInstallation
Scopes: any signed-in principal
Idempotency-Key: required

Request body (application/json, required): GitHubConnectRequest

Field	Type	Description
`installation_id` *	integer
`setup_action`	`install`, `update`, `request`
`code`	string	OAuth authorisation code returned by GitHub when user authorisation is enabled.
`state` *	string

Responses

Status	Meaning	Body
`201` Created	Created.	GitHubInstallation

Errors: 400, 401, 403, 409, 422, 429, 500, as problem+json with a stable code.

Example

curl -X POST https://api.guv.dev/v1/github/installations \
  -H "Authorization: Bearer $GUV_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "installation_id": 1,
  "setup_action": "install",
  "code": "string",
  "state": "string"
}'

Example response

{
  "id": "ghi_01jbx2m9k7q4r8t5v6w3y0z1pr",
  "workspace_id": "string",
  "installation_id": 1,
  "account": {
    "login": "string",
    "type": "User",
    "avatar_url": "string"
  },
  "repository_selection": "all",
  "suspended": false,
  "created_at": "2026-10-22T13:05:00Z"
}

List connected GitHub installations

GET /v1/workspaces/{workspace}/github/installations

Operation: listGitHubInstallations
Scopes: projects:read
Paginated: ?limit= and ?cursor=

Parameters

Name	In	Type	Description
`workspace` *	path	string	Workspace id (`ws_…`) or slug.

Responses

Status	Meaning	Body
`200` OK	A page of GitHubInstallation objects.	GitHubInstallationList

Errors: 400, 401, 403, 404, 429, 500, as problem+json with a stable code.

Example

curl https://api.guv.dev/v1/workspaces/acme/github/installations \
  -H "Authorization: Bearer $GUV_TOKEN"

Example response

{
  "data": [
    {
      "id": "ghi_01jbx2m9k7q4r8t5v6w3y0z1pr",
      "workspace_id": "string",
      "installation_id": 1,
      "account": {
        "login": "string",
        "type": "User",
        "avatar_url": "string"
      },
      "repository_selection": "all",
      "suspended": false,
      "created_at": "2026-10-22T13:05:00Z"
    }
  ],
  "next_cursor": "string",
  "has_more": false
}

List repositories the installation can see

GET /v1/workspaces/{workspace}/github/installations/{installation_id}/repositories

Operation: listGitHubRepositories
Scopes: projects:read
Paginated: ?limit= and ?cursor=

Parameters

Name	In	Type	Description
`workspace` *	path	string	Workspace id (`ws_…`) or slug.
`installation_id` *	path	string	Guv GitHub installation id (`ghi_…`).
`q`	query	string	Filter by name.

Responses

Status	Meaning	Body
`200` OK	A page of GitHubRepository objects.	GitHubRepositoryList

Errors: 400, 401, 403, 404, 429, 500, as problem+json with a stable code.

Example

curl https://api.guv.dev/v1/workspaces/acme/github/installations/ins_01jbx2m9k7q4r8t5v6w3y0z1pr/repositories \
  -H "Authorization: Bearer $GUV_TOKEN"

Example response

{
  "data": [
    {
      "id": 1,
      "full_name": "primecarers/platform",
      "private": false,
      "default_branch": "string",
      "language": "string",
      "has_manifest": false,
      "pushed_at": "2026-10-22T13:05:00Z"
    }
  ],
  "next_cursor": "string",
  "has_more": false
}

Detect the stack of a repository and suggest a guv.yaml

POST /v1/workspaces/{workspace}/github/detect

Operation: detectStack
Scopes: projects:read
CLI: guv init
Idempotency-Key: optional

Parameters

Name	In	Type	Description
`workspace` *	path	string	Workspace id (`ws_…`) or slug.

Request body (application/json, required): StackDetectRequest

Field	Type	Description
`installation_id` *	string
`repo` *	string
`branch`	string
`root`	string	Default `.`.

Responses

Status	Meaning	Body
`200` OK	OK.	StackDetection

Errors: 400, 401, 403, 404, 409, 422, 429, 500, as problem+json with a stable code.

Example

curl -X POST https://api.guv.dev/v1/workspaces/acme/github/detect \
  -H "Authorization: Bearer $GUV_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "installation_id": "string",
  "repo": "string",
  "branch": "string",
  "root": "."
}'

Example response

{
  "summary": "We'll build a Next.js app with Node 22 and give you a Postgres database.",
  "has_manifest": false,
  "services": [
    {
      "name": "string",
      "root": "string",
      "builder": "railpack",
      "language": "string",
      "framework": "string",
      "start": "string",
      "port": 1
    }
  ],
  "databases": [
    "postgres"
  ],
  "variables": [
    {
      "name": "string",
      "example": "string",
      "likely_secret": false
    }
  ],
  "suggested_manifest": "string"
}

GitHub App webhook receiver

POST /v1/integrations/github/webhook

Called by GitHub. Authenticated by X-Hub-Signature-256; deduplicated by X-GitHub-Delivery instead of Idempotency-Key.

Operation: receiveGitHubWebhook
Scopes: none (public)

Request body (application/json, required): object

Responses

Status	Meaning	Body
`204` No Content	Done. No body.	none

Errors: 400, 401, 409, 422, 429, 500, as problem+json with a stable code.

Example

curl -X POST https://api.guv.dev/v1/integrations/github/webhook \
  -H "Authorization: Bearer $GUV_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'