GitHub API: Manage GitHub App Installations

The GitHub API manages GitHub App installations that grant Springwinter read access to your repositories for builds and deployments. Installing the GitHub App on a GitHub account or organization lets Springwinter clone source code, detect pushes, and create per-branch preview environments automatically. Use these endpoints to start the install flow, complete it after the GitHub redirect, and manage existing installations.

Start the GitHub App Install Flow

POST /api/github/installation_setup Begin the GitHub App installation flow. Returns a redirect URL that you open in a browser to grant Springwinter access to your GitHub account or organization. After you approve the installation on GitHub, the flow completes automatically.

curl -X POST https://springwinter.dev/api/github/installation_setup \
  -H "Authorization: Bearer swt_yourtoken"

{
  "redirect_url": "https://github.com/apps/springwinter/installations/new?state=sw_state_abc123"
}

string

The GitHub URL to open in a browser. After the user approves the installation, GitHub redirects back to Springwinter, which completes the flow automatically.

List GitHub Installations

GET /api/github/installations Return all GitHub App installations connected to your Springwinter organization.

curl https://springwinter.dev/api/github/installations \
  -H "Authorization: Bearer swt_yourtoken"

{
  "installations": [
    {
      "installation_id": 12345678,
      "account_login": "acme-corp",
      "account_type": "Organization"
    },
    {
      "installation_id": 87654321,
      "account_login": "alexkim",
      "account_type": "User"
    }
  ]
}

array

Array of GitHub App installation objects.

Show Installation object fields

integer

The GitHub-assigned installation ID. Use this in subsequent endpoints.

The GitHub username or organization name where the app is installed.

string

Either "User" or "Organization".

Complete the GitHub App Install

POST /api/github/installations Finalize the GitHub App installation after GitHub redirects back to Springwinter. In most cases, Springwinter completes this step automatically via the redirect handler — call this endpoint manually only if the automatic completion fails.

curl -X POST https://springwinter.dev/api/github/installations \
  -H "Authorization: Bearer swt_yourtoken" \
  -H "Content-Type: application/json" \
  -d '{ "installation_id": 12345678 }'

{
  "installation_id": 12345678,
  "account_login": "acme-corp",
  "account_type": "Organization"
}

integer

required

The GitHub installation ID returned in the callback URL query parameter installation_id after the user approves the GitHub App.

Remove a GitHub Installation

DELETE /api/github/installations/ Remove a GitHub App installation record from Springwinter. This tells Springwinter to forget the installation — it stops being used for new builds and deployments. This action does not uninstall the GitHub App from GitHub itself.

Removing an installation from Springwinter does not uninstall the GitHub App. Any services configured to deploy from a repository in this installation will stop receiving automatic deployments. To fully revoke Springwinter’s access to your GitHub account, also uninstall the app from GitHub → Settings → Applications → Springwinter → Uninstall.

curl -X DELETE https://springwinter.dev/api/github/installations/12345678 \
  -H "Authorization: Bearer swt_yourtoken"

{
  "installation_id": 12345678,
  "deleted": true
}

integer

required

The GitHub installation ID to remove from Springwinter.

List Repositories

GET /api/github/installations//repositories List all repositories accessible through a specific GitHub App installation. These are the repositories you granted Springwinter access to when you installed the GitHub App. Use this to discover which repos are available when configuring a web server, worker, or static website.

curl https://springwinter.dev/api/github/installations/12345678/repositories \
  -H "Authorization: Bearer swt_yourtoken"

{
  "repositories": [
    {
      "id": 441234567,
      "full_name": "acme-corp/api-service",
      "private": true,
      "default_branch": "main"
    },
    {
      "id": 441234568,
      "full_name": "acme-corp/marketing-site",
      "private": false,
      "default_branch": "main"
    },
    {
      "id": 441234569,
      "full_name": "acme-corp/data-worker",
      "private": true,
      "default_branch": "develop"
    }
  ]
}

array

Array of repository objects accessible through the installation.

Show Repository object fields

integer

GitHub’s internal repository ID.

string

Repository path in owner/repo format.

boolean

true if the repository is private.

string

The repository’s default branch name, used as the deploy target when no branch is explicitly specified.

If a repository you expect to see is missing, check that it was included in the GitHub App’s repository access list. You can update the list from GitHub → Settings → Applications → Springwinter → Repository access.

When a build starts, Springwinter mints a short-lived GitHub installation token scoped to the specific repository being built. The token expires automatically and is not stored after the build completes. Springwinter never retains persistent GitHub credentials.

Overview

Projects & Resources

Data & Storage

Account

GitHub API: Manage GitHub App Installations

Start the GitHub App Install Flow

List GitHub Installations

Complete the GitHub App Install

Remove a GitHub Installation

List Repositories

​Start the GitHub App Install Flow

​List GitHub Installations

​Complete the GitHub App Install

​Remove a GitHub Installation

​List Repositories

Start the GitHub App Install Flow

List GitHub Installations

Complete the GitHub App Install

Remove a GitHub Installation

List Repositories