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

# Connect GitHub to Springwinter for Automatic Deploys

> Install the Springwinter GitHub App to trigger automatic builds on push, enable branch preview environments, and manage repository access.

Springwinter integrates with GitHub through an official GitHub App that you install on your personal account or organization. Once installed, Springwinter can listen for push events on the repositories you select, trigger builds automatically, and create isolated preview environments for feature branches — all without you ever sharing a personal access token or setting up a webhook manually.

## Install the GitHub App

<Steps>
  <Step title="Open GitHub settings in the dashboard">
    Log in to the Springwinter dashboard and navigate to **Settings → GitHub**. If you have not yet connected a GitHub account, you will see the **Connect GitHub** button.
  </Step>

  <Step title="Start the GitHub App installation">
    Click **Connect GitHub**. You are redirected to the GitHub App installation page on GitHub.com. If you are not already logged into GitHub, you will be prompted to do so.
  </Step>

  <Step title="Choose the GitHub account or organization">
    On the installation page, select the GitHub account — your personal account or any organization you administer — where you want to install the Springwinter App. If you manage multiple organizations, you can install the app separately on each one; each installation is independent.
  </Step>

  <Step title="Select repository access">
    Choose how much access to grant:

    * **All repositories** — Springwinter can see and build every current and future repository in the account or organization.
    * **Only select repositories** — pick specific repositories from the list. You can add more later by revisiting the GitHub App settings.

    Select the option that matches your team's security posture and click **Install**.
  </Step>

  <Step title="Confirm and return to Springwinter">
    GitHub asks you to confirm the installation. After you click **Install & Authorize**, GitHub redirects you back to the Springwinter dashboard automatically. Your installation appears immediately under **Settings → GitHub** with the account name and the number of repositories accessible.
  </Step>
</Steps>

## What Springwinter does with GitHub access

Springwinter requests the minimum permissions required to build and deploy your code:

* **Read repository contents** — to clone your repository at the commit SHA being deployed.
* **Read repository metadata** — to populate the repository and branch selectors in the dashboard.
* **Receive push webhook events** — to trigger builds automatically when you push to a configured branch.

When a build starts, Springwinter mints a short-lived GitHub installation token scoped to the target repository. That token is used to clone the repository and is discarded immediately afterward. Springwinter does not store GitHub tokens between builds.

<Note>
  A GitHub installation token is created at the start of each build and is not stored by Springwinter after the clone step completes. Your repository credentials are never written to a database or accessible outside the build process.
</Note>

## Auto-deploy behavior

Every resource (web server, worker, or static website) is linked to a specific GitHub repository and branch at creation time. When you push a commit to that branch:

1. GitHub delivers a push webhook to Springwinter.
2. Springwinter queues a new build for the resource.
3. The build clones your repository at the new commit, builds the artifact (Docker image or static output), and deploys it.
4. The resource's dashboard card updates to show the new commit SHA and deployment status.

Auto-deploy is enabled by default. You can disable it on a per-resource basis from the resource's settings panel if you prefer to trigger deploys manually or through the API.

## Branch preview environments

Any branch in your repository can be promoted to a preview environment — a fully isolated copy of your service with its own URL. Previews are useful for testing feature branches, reviewing pull requests, and running QA against real infrastructure before merging.

Each preview environment has its own URL and its own set of environment variables. Pushing new commits to the preview branch updates the preview automatically, following the same auto-deploy behavior as your production branch.

<Tip>
  For more on how previews work, including how to create them and manage their lifecycle, see [Branch Preview Environments](/concepts/previews).
</Tip>

## Disconnect a GitHub installation

To remove a GitHub installation from Springwinter, you have two options:

**Via the API:**

```bash theme={null}
curl -X DELETE https://springwinter.dev/api/github/installations/{installation_id} \
  -H "Authorization: Bearer <your-api-token>"
```

**Via GitHub:**

Open **GitHub.com → Settings → Applications → Installed GitHub Apps**, find the Springwinter App, and click **Configure → Uninstall**. GitHub notifies Springwinter, which marks the installation as disconnected in your dashboard.

<Warning>
  Removing a GitHub installation does not delete any deployed resources. Services currently running in your AWS account continue to run. However, auto-deploy stops working immediately — subsequent pushes will not trigger new builds until you reconnect a GitHub installation.
</Warning>

## Multiple GitHub accounts and organizations

<Tip>
  You can install the Springwinter GitHub App on multiple personal accounts and organizations. Each installation is tracked independently in **Settings → GitHub**, and you can grant different repository subsets to each one. When adding a resource, you choose which installation to pull from, so you can deploy code from multiple organizations into the same Springwinter project.
</Tip>