Deploy from GitHub
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.
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.
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).
Your code is on GitLab, Bitbucket, Gitea or your own Git server? Use Deploy from any Git URL instead.
Steps
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
ghCLI 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 (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.
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.
“Local only” badge
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.
Check the settings
The deploy screen 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.
Press Deploy
You land on the build screen, which streams the logs live. When it finishes, you get a link to your app.
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.
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.
CLI
# 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> --enableInside a local clone linked with synq init, plain synq deploy deploys the linked project and the
current branch.
Troubleshooting
No repositories show up
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.
The build failed
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 and GitHub troubleshooting.
Related guides
Guides
Choose a task, follow the steps, and use the matching CLI or SDK reference when you need more detail.
Deploy from any Git URL
Deploy a repository from GitLab, Bitbucket, Gitea, Forgejo, Codeberg or your own Git server, over HTTPS or SSH, with an access token or a deploy key Synq generates. Covers SSH host key pinning, branches, monorepos and changing the source later.