# Deploy from GitHub
URL: https://synquic.tech/docs/guides/deploy-from-github.md

Connect GitHub once, pick a repository, check the detected build and deploy. Then turn on auto-deploy so every push ships. Includes the CLI way.

import { Step, Steps } from 'fumadocs-ui/components/steps';

This is the most common way to use Synq: take code that lives on GitHub and turn it into a running app with
its own address. You connect GitHub once, pick a repository, and Synq detects how to build it.

<Callout title="What you need first">
- Access to your Synq panel.
- A GitHub repository with your app in it.
- That's it. You do **not** need a Dockerfile or config files; Synq works them out (see
  [Build detection](/docs/guides/build-detection)).
</Callout>

Your code is on GitLab, Bitbucket, Gitea or your own Git server? Use
[Deploy from any Git URL](/docs/guides/deploy-from-git-url) instead.

## Steps

<Steps>

<Step>

### Connect GitHub (once)

Synq needs permission to read your repositories. Click **New Project** in the sidebar; the **GitHub** tab
opens first. If GitHub is not connected yet, it shows **Connect GitHub to deploy** with the ways to connect:

- **Sign in with GitHub**: a browser sign-in with a one-time device code. No app to register, no SSH into
  the server.
- **SSH key or access token**: bring your own credential, a deploy key per server or a personal access
  token.
- **Manual GitHub connection** (**Set up in Settings**): your own GitHub App or OAuth app, or the `gh` CLI
  on the Synq host.

All of these are also in **Settings → Git** ("Pick how Synq reaches your repositories."):

| Method | What it is | Good for |
|---|---|---|
| **GitHub App** | Your own [self-hosted GitHub App](/docs/guides/self-hosted-github-app) (one-click manifest, or register an existing one). Short-lived, repository-scoped installation tokens. | Teams, remote servers, auto-deploy without per-repo webhooks. |
| **GitHub sign-in** | **Log in with GitHub** shows a one-time code and a `github.com/login/device` link. Set `GITHUB_CLIENT_ID` to your own GitHub App or OAuth app's client ID (device flow enabled). | One person, quick setup. |
| **gh CLI on this host** | If `gh` on the Synq host is signed in, Synq picks it up; otherwise run the shown `gh auth login` on the server. | Single-server installs. |
| **GitHub token** | A personal access token, under **Clone credentials**. Usable everywhere. | Headless setups. |

Synq never puts its own GitHub identity in place of yours. Which credential clones on which server is
explained in [Git authentication for private repos](/docs/guides/git-authentication).

</Step>

<Step>

### Pick the repository

The **GitHub** tab lists your repositories. Use the account row at the top to switch between the GitHub
users and organizations you granted (**+** adds another), **Search repositories...**, the **All**,
**Public** and **Private** filters, and the **Recent**, **Name** and **Stars** sort. Click a repository.

<Callout title="“Local only” badge" type="warn">
A repository marked **Local only** is visible through the `gh` CLI, but your GitHub App is not installed on
its owner. It can build on the Synq host, but deploys that build on another server are refused. Install
the App on that owner (**Install GitHub App**) to enable them.
</Callout>

</Step>

<Step>

### Check the settings

The [deploy screen](/docs/dashboard/deploy-wizard) shows what Synq detected: the framework (or **Dockerfile
Detected** when the repository has a root Dockerfile), the install, build and start commands, and the port.
In the sidebar, pick the **branch**, add a **Domain**, and read the **Deploy Summary**.

The bar at the top (**Build & deploy:**) shows which server the app runs on and where it builds. Click it
to choose another server for this deploy.

For most apps you change nothing here. See a field you don't recognize? Leave it.

</Step>

<Step>

### Press Deploy

You land on the build screen, which streams the logs live. When it finishes, you get a link to your app.

</Step>

</Steps>

## Turn on auto-deploy

By default you deploy when you choose to. To redeploy every time you push to GitHub, open the project,
then **Source & Triggers → Source**, and switch on **Auto Deploy**. Every push to the deploy branch then
builds and ships automatically. Details, including private installs without a public address, are in
[Auto-deploy on push](/docs/guides/auto-deploy#github).

## Change the builder

Synq builds a repository with a root Dockerfile from that Dockerfile, and anything else with generated
framework settings. To use Nixpacks, Railpack, Cloud Native Buildpacks, or a Dockerfile in another path,
change the project's **Builder**. See [Build detection and builders](/docs/guides/build-detection).

## CLI

```bash
# Create a project pointing at your repository
synq project create --name my-app --git-owner your-name --git-repo my-app --git-branch main

# Ship it (the create command prints the project ID)
synq deploy --project <project-id> --watch

# Optional: redeploy on every push
synq project git auto-deploy <project-id> --enable
```

Inside a local clone linked with `synq init`, plain `synq deploy` deploys the linked project and the
current branch.

## Troubleshooting

<Callout title="No repositories show up" type="warn">
The GitHub connection did not finish, or Synq has no permission for that repository. Open
**Settings → Git**, reconnect, and when GitHub asks which repositories to grant, include yours.
</Callout>

<Callout title="The build failed" type="error">
Open the build screen and read the last few red lines; that is the real reason. Most first-time failures
are a missing build command, a missing environment variable, or the app listening on the wrong port. See
[Troubleshooting → Deployments](/docs/troubleshooting/deployments) and
[GitHub troubleshooting](/docs/troubleshooting/github).
</Callout>

## Related guides

<Cards>
  <Card title="Auto-deploy on push" href="/docs/guides/auto-deploy" description="Ship every commit automatically." />
  <Card title="Add a custom domain" href="/docs/guides/custom-domains" description="Put your app on your own address with automatic HTTPS." />
  <Card title="Environment variables" href="/docs/guides/environment-variables" description="Give your app its secrets and settings, safely." />
</Cards>