> ## Documentation Index
> Fetch the complete documentation index at: https://docs.springwinter.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# GitHub API: Manage GitHub App Installations

> REST endpoints to install, list, and remove the Springwinter GitHub App, and to list repositories available for builds and deployments.

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.

<CodeGroup>
  ```bash Request theme={null}
  curl -X POST https://springwinter.dev/api/github/installation_setup \
    -H "Authorization: Bearer swt_yourtoken"
  ```

  ```json Response theme={null}
  {
    "redirect_url": "https://github.com/apps/springwinter/installations/new?state=sw_state_abc123"
  }
  ```
</CodeGroup>

<ResponseField name="redirect_url" type="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.
</ResponseField>

***

## List GitHub Installations

**GET /api/github/installations**

Return all GitHub App installations connected to your Springwinter organization.

<CodeGroup>
  ```bash Request theme={null}
  curl https://springwinter.dev/api/github/installations \
    -H "Authorization: Bearer swt_yourtoken"
  ```

  ```json Response theme={null}
  {
    "installations": [
      {
        "installation_id": 12345678,
        "account_login": "acme-corp",
        "account_type": "Organization"
      },
      {
        "installation_id": 87654321,
        "account_login": "alexkim",
        "account_type": "User"
      }
    ]
  }
  ```
</CodeGroup>

<ResponseField name="installations" type="array">
  Array of GitHub App installation objects.

  <Expandable title="Installation object fields">
    <ResponseField name="installation_id" type="integer">
      The GitHub-assigned installation ID. Use this in subsequent endpoints.
    </ResponseField>

    <ResponseField name="account_login" type="string">
      The GitHub username or organization name where the app is installed.
    </ResponseField>

    <ResponseField name="account_type" type="string">
      Either `"User"` or `"Organization"`.
    </ResponseField>
  </Expandable>
</ResponseField>

***

## 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.

<CodeGroup>
  ```bash Request theme={null}
  curl -X POST https://springwinter.dev/api/github/installations \
    -H "Authorization: Bearer swt_yourtoken" \
    -H "Content-Type: application/json" \
    -d '{ "installation_id": 12345678 }'
  ```

  ```json Response (201 Created) theme={null}
  {
    "installation_id": 12345678,
    "account_login": "acme-corp",
    "account_type": "Organization"
  }
  ```
</CodeGroup>

<ParamField body="installation_id" type="integer" required>
  The GitHub installation ID returned in the callback URL query parameter `installation_id` after the user approves the GitHub App.
</ParamField>

***

## Remove a GitHub Installation

**DELETE /api/github/installations/{installation_id}**

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.

<Warning>
  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**.
</Warning>

<CodeGroup>
  ```bash Request theme={null}
  curl -X DELETE https://springwinter.dev/api/github/installations/12345678 \
    -H "Authorization: Bearer swt_yourtoken"
  ```

  ```json Response (200 OK) theme={null}
  {
    "installation_id": 12345678,
    "deleted": true
  }
  ```
</CodeGroup>

<ParamField path="installation_id" type="integer" required>
  The GitHub installation ID to remove from Springwinter.
</ParamField>

***

## List Repositories

**GET /api/github/installations/{installation_id}/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.

<CodeGroup>
  ```bash Request theme={null}
  curl https://springwinter.dev/api/github/installations/12345678/repositories \
    -H "Authorization: Bearer swt_yourtoken"
  ```

  ```json Response theme={null}
  {
    "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"
      }
    ]
  }
  ```
</CodeGroup>

<ResponseField name="repositories" type="array">
  Array of repository objects accessible through the installation.

  <Expandable title="Repository object fields">
    <ResponseField name="id" type="integer">GitHub's internal repository ID.</ResponseField>
    <ResponseField name="full_name" type="string">Repository path in `owner/repo` format.</ResponseField>
    <ResponseField name="private" type="boolean">`true` if the repository is private.</ResponseField>
    <ResponseField name="default_branch" type="string">The repository's default branch name, used as the deploy target when no branch is explicitly specified.</ResponseField>
  </Expandable>
</ResponseField>

<Tip>
  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**.
</Tip>

***

<Note>
  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.
</Note>