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

# GitHub Integration

> Connect a GitHub repository for automatic deployments

Connect your GitHub account to Shuttle to manage and deploy repositories directly from the Shuttle console. You can turn on automatic deployments when you push code to GitHub. When enabled, this integration streamlines your deployment workflow by automatically rebuilding and redeploying your application whenever changes are pushed.

## How It Works

When you connect a GitHub repository to your Shuttle project, we establish a direct link between your codebase and your deployment pipeline.

### Features

* **Deploy Your Own Repository**: Connect your existing GitHub repository to Shuttle, configure your secrets, and deploy your application from Shuttle dashboard
* **Automatic Deployments on Git Push**: Enable automatic deployments so that pushing code to your selected branch triggers an immediate rebuild and redeployment
* **Deploy Templates**: Choose from our pre-configured GitHub templates and deploy them instantly to get started quickly - no CLI installation required
* **Deploy From Dashboard**: Deploy any branch from your repository directly using the "Deploy" button in the console dashboard

<Warning>
  ### Use-cases and limitations

  If your project relies on gitignored assets that are needed when running `shuttle deploy`, you can instead use our [GitHub Deploy Action](/integrations/ci-cd), and build/configure these assets prior to deployment.

  Shuttle's automatic deployments from GitHub are designed for projects where the codebase is fully ready to deploy with `shuttle deploy` after checkout.
</Warning>

## Which Should I Use?

| Your Project                                   | Use This               |
| :--------------------------------------------- | :--------------------- |
| Pure Rust backend (Axum, Actix, Rocket)        | **GitHub Integration** |
| Rust + pre-built static files committed to git | **GitHub Integration** |
| Rust + React/Vue build step                    | **GitHub Actions**     |
| Rust + Asset compilation (SCSS, Tailwind)      | **GitHub Actions**     |
| Rust + Code generation before deploy           | **GitHub Actions**     |

## Connecting Your GitHub Account

To integrate GitHub with your Shuttle project, follow these steps:

1. Navigate to the [Integrations page](https://console.shuttle.dev/account/integrations) in Shuttle Console.
2. Click "Connect to GitHub" to authorise Shuttle to access your selected repositories.
3. GitHub will prompt you to provide access.

## Deploying a GitHub Repository

1. Navigate to [new project](https://console.shuttle.dev/new-project) and select "**GitHub Repository".**
2. Once authorised, select the repository you want to deploy.
3. Confirm the repository is configured to run on Shuttle. See the [migration docs](/migration/guide) for guidance.
4. Select the branch and add secrets if required.
5. Confirm deployment and your project will be deployed to Shuttle 🚀

## Connecting a GitHub Repository to an Existing Project

1. Navigate to **project** **settings** of your desired project.
2. Once authorised, select the repository you want to connect to this Shuttle project.
3. After selecting your repository, confirm the connection. Your Shuttle project is now linked to your GitHub repository.

*Disconnecting removes the link between Shuttle and your repository but doesn't affect your deployed application or your GitHub repository itself.*

## Automatic Deployments

Once you've connected a GitHub repository to your Shuttle project, you can push to GitHub and Shuttle will automatically pull the latest code from your connected repository, build it, and deploy the updated application.

1. Navigate to project settings and ensure a GitHub repository is connected.
2. Enable **Automatic Deployments**
3. Select and confirm branch.
4. Push to GitHub and a deployment will automatically begin.

## Deploying a GitHub Template

Deploying a template sets up both the Shuttle project and a new GitHub repository in your connected GitHub account. You get a fully functional application deployed on Shuttle with the complete source code in your GitHub account.

1. Navigate to [Shuttle Console](https://console.shuttle.dev/new-project) and select "**Template".**
2. Select desired template.
3. Choose "**Deploy from GitHub**" development flow and authorise if required.
4. Select which GitHub account you would like the template to be generated to and name repository.
5. If required, add secrets and **deploy**.

## Permissions for Growth Tier

**Team members on a Growth plan** have **view access** to GitHub integration settings but cannot modify them.

* Team members are unable to connect a repository, disconnect or change a linked repository.
* **Both** account **owners** and **team** members can **enable** **automatic** **deployments** and **deploy** a **connected** **repository**.