VCS installations

These endpoints link GitHub App and GitLab installations to a tenant for Stategraph Orchestration. They also read and manage the repositories, pull requests, dirspaces, and work manifests of each installation. See Enable orchestration for the server-side setup.

Tenant installations

These endpoints link installations to a tenant.

• GitHub identity claims require GITHUB_APP_CLIENT_ID and GITHUB_APP_CLIENT_SECRET on the server (503 otherwise).
• GitLab provisioning requires Stategraph Orchestration (503 when unavailable).

Installations

Most of the endpoints below exist for both GitHub and GitLab, with the same parameters and responses. Each entry lists its paths. These path parameters are strings:

• installation_id: the installation. A GitLab installation is a GitLab group, and its installation ID is the numeric group ID.
• repo_id: the repository. A GitLab repository is a GitLab project, and its repository ID is the numeric project ID.
• work_manifest_id: the work manifest.

Four GitLab endpoints call GitLab with the GitLab account that is linked to the caller. They list installations and groups, return the webhook, and set the access token. To link a GitLab group to a tenant, use the tenant installation endpoints.

List installations

GET /api/v1/user/github/installations
GET /api/v1/gitlab/installations

Returns the GitHub or GitLab installations that the current user can access. Status codes: 200, 403.

{
  "installations": [...]
}

curl -X GET \
  https://app.stategraph.cloud/api/v1/user/github/installations \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

curl -X GET \
  https://app.stategraph.cloud/api/v1/gitlab/installations \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

List GitLab groups

GET /api/v1/gitlab/groups

Returns the GitLab groups that the GitLab account of the current user can see, sorted by name. Each entry has the numeric group ID and the full group name. Status codes: 200.

[
  {
    "id": 1043,
    "name": "Acme"
  }
]

Get GitLab webhook

GET /api/v1/gitlab/installations/{id}/webhook

Registers a GitLab group as an installation if it is not one yet, and returns the webhook settings to configure in GitLab. The caller must have the Maintainer or Owner role in the group. id (integer) is the GitLab group ID.

Status codes: 200, and 403 when the caller does not have the Maintainer or Owner role in the group.

Response (schema gitlab-webhook):

{
  "state": "pending",
  "webhook_secret": "string",
  "webhook_url": "https://app.stategraph.cloud/api/v1/gitlab/events"
}

Set GitLab access token

PUT /api/v1/gitlab/installations/{installation_id}/access-token

Creates or updates the GitLab access token that Orchestration uses to call GitLab for a group. The caller must have the Maintainer or Owner role in the group. Status codes: 200, 403.

Request body (schema gitlab-access-token):

{
  "access_token": "string"
}

curl -X PUT \
  https://app.stategraph.cloud/api/v1/gitlab/installations/{installation_id}/access-token \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"access_token": "YOUR_GITLAB_TOKEN"}'

Repositories and pull requests

List repositories

GET /api/v1/github/installations/{installation_id}/repos
GET /api/v1/gitlab/installations/{installation_id}/repos

Returns the repositories of an installation. Status codes: 200, 403.

{
  "repositories": [...]
}

Refresh repositories

POST /api/v1/github/installations/{installation_id}/repos/refresh

Starts a refresh of the repositories of a GitHub installation. Returns a task ID to poll with GET /api/v1/tasks/{task_id}. Status codes: 200, 403.

{
  "id": "string"
}

Delete repository

DELETE /api/v1/github/installations/{installation_id}/repos/{repo_id}
DELETE /api/v1/gitlab/installations/{installation_id}/repos/{repo_id}

Removes a repository from an installation:

• GitHub: the repository must be archived on GitHub, and the caller must be an admin of the organization that owns it.
• GitLab: the project must be archived in GitLab, and the caller must have the Maintainer or Owner role in the group that owns it.

Status codes: 200 with an empty object, 400 with the error id INVALID_REPO_ID, REPO_NOT_FOUND, or REPO_NOT_ARCHIVED, and 403.

curl -X DELETE \
  https://app.stategraph.cloud/api/v1/github/installations/{installation_id}/repos/{repo_id} \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

curl -X DELETE \
  https://app.stategraph.cloud/api/v1/gitlab/installations/{installation_id}/repos/{repo_id} \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

List pull requests

GET /api/v1/github/installations/{installation_id}/pull-requests

Returns the pull requests of a GitHub installation. Status codes: 200, 403.

{
  "pull_requests": [...]
}

Dirspaces and work manifests

List dirspaces

GET /api/v1/github/installations/{installation_id}/dirspaces
GET /api/v1/gitlab/installations/{installation_id}/dirspaces

Returns the directory and workspace pairs (dirspaces) of an installation. Status codes: 200, 400, 403.

{
  "dirspaces": [...]
}

List work manifests

GET /api/v1/github/installations/{installation_id}/work-manifests
GET /api/v1/gitlab/installations/{installation_id}/work-manifests

Returns the work manifests of an installation. Status codes: 200, 400, 403.

{
  "work_manifests": [...]
}

Get work manifest

GET /api/v1/github/installations/{installation_id}/work-manifests/{work_manifest_id}
GET /api/v1/gitlab/installations/{installation_id}/work-manifests/{work_manifest_id}

Returns the details of a work manifest. Status codes: 200, 403, 404.

Get work manifest outputs

GET /api/v1/github/installations/{installation_id}/work-manifests/{work_manifest_id}/outputs
GET /api/v1/gitlab/installations/{installation_id}/work-manifests/{work_manifest_id}/outputs

Returns the outputs and steps of a work manifest. Status codes: 200, 400, 403, 404.

{
  "steps": [...]
}

List workspaces

POST /api/github/v1/work-manifests/{work_manifest_id}/workspaces

Returns the workspaces of a GitHub work manifest (schema work-manifest-workspaces). Status codes: 200, 403.

curl -X POST \
  https://app.stategraph.cloud/api/github/v1/work-manifests/{work_manifest_id}/workspaces \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"