Deploy from GitHub
Connect a GitHub repository and put it online — the step-by-step way and the one-command way.
This is the most common thing people do with Openship: take some code that lives on GitHub and make it a real, working website with its own address. Think of it like this — your code is a recipe, and Openship is the kitchen that cooks it and serves the meal. You point Openship at the recipe once, and it does the rest.
What you need first
- An Openship account (you're already in if you can see the dashboard).
- A GitHub repository with your app in it.
- That's it. You do not need Docker, a server, or any config files — Openship figures those out.
Steps
Connect your GitHub account (once)
Openship needs permission to read your repository. You only do this one time.
Go to Settings → Git and choose a GitHub connection method. A GitHub window may open asking "do you allow this?" — say yes. When it closes, you're connected.
Self-hosted: two ways to connect (no Openship account required)
On a self-hosted instance you're never forced through Openship Cloud. Settings → Git offers:
- Openship Cloud GitHub App — the managed App (short-lived tokens, great for remote-server deploys). Optional; it needs an Openship Cloud connection.
- Your own self-hosted GitHub Apps — use the one-click manifest flow or register one or more existing GitHub/GitHub Enterprise Apps in the dashboard, then use installation tokens without Openship Cloud or PATs. See Self-hosted GitHub App.
- Manual — connect with your own GitHub identity, no Openship in the middle:
ghCLI on the instance — press Log in with GitHub; if the instance hasghauthenticated it's picked up immediately, otherwise run the showngh auth loginon the box and the page detects it automatically.- Your own GitHub OAuth/App (device login) — set
GITHUB_CLIENT_ID(a public client id from a GitHub App/OAuth app you register, with device flow enabled) and Log in with GitHub shows a one-time code +github.com/login/devicelink right in the UI — no terminal, no Openship client id. - A clone token — or just add a personal access token under Clone credentials.
Pick whichever fits; Openship never substitutes its own GitHub identity for yours on a self-hosted box.
Pick the repository you want to deploy
Open the Library page (the "New project" button takes you here too). Choose the Repositories tab — you'll see a list of your GitHub repos. Click the one you want.
Choose where it should run
Openship asks where to run your app. Pick the one that fits:
- Local — on this computer (great for trying things out on the desktop app).
- Server — on one of your own connected servers.
- Cloud — on Openship Cloud, where we run it for you.
If you're just starting, the default choice is fine — you can move it later.
Check the settings and press Deploy
Openship shows a summary: which framework it detected, the build command, and the web address it will use. For most apps you don't change anything here.
Press Deploy.
Tip
See a field you don't recognize? Leave it. Openship's detected defaults are correct for the large majority of apps — you only override things when you have a specific reason.
Watch it go live
You land on the build screen, which streams the logs live — like watching the oven through the glass door. When it finishes, you get a link. Click it, and your app is online. 🎉
Turn on auto-deploy (optional but great)
By default you deploy when you choose to. If you'd like Openship to redeploy every time you push to GitHub, turn on auto-deploy:
Open your project → Source tab → switch on Auto-deploy. From now on, every git push to your
deploy branch rebuilds and ships automatically.
GitHub deployment Checks
GitHub-backed projects report their deployment result and individual service results on the deployed commit by default, on both self-hosted Openship and Openship Cloud. This requires a connected GitHub App with Checks: Read and write access to the repository. A clone token alone does not enable this integration.
Open Project → Source → GitHub deployment checks, or use the same control in the deployment wizard. Turn reporting off, or expand Customize checks to select the overall result, all services, specific services, and whether to include failure details. These settings apply to new deployment attempts. Turning reporting off also closes pending Checks from an active attempt.
Checks show queued, running and completed outcomes, including failed builds, cancellations and partial service failures. Each links to its deployment in Openship. Failure details are redacted summaries visible to people who can read the repository; full build logs are not attached. Delivery retries in the background if GitHub is unavailable and never blocks the deployment. Connection problems appear beside these settings.
Check names include the project and environment: Openship / <project> / <environment>.
Service Checks append / <service>. If a GitHub repository rule requires an older
build:<service> Check, select the new name after its first report.
GitHub's Re-run action retries the recorded commit. A service Check retries that service; the overall Check retries the project. The instance must be reachable by GitHub webhooks to receive this action. Reporting results itself only needs an outbound GitHub connection.
These deployment results are separate from workflow Checks required before deployment. Configure those in Project Actions.
CLI
Everything above works from the CLI too:
# Create a project pointing at your repo
openship project create --name my-app --git-owner your-name --git-repo my-app
# Ship it
openship deploy
# Optional: redeploy on every push
openship project git auto-deploy my-app --enableTroubleshooting
“Connect GitHub” does nothing / no repos show up
Your GitHub connection didn't finish, or Openship has no permission for that repo. Go back to Settings → General, disconnect, and connect again — and when GitHub asks which repositories to grant, make sure your repo is included.
The build failed
Open the build screen and read the last few red lines — that's the real reason. Most first-time failures are one of: a missing build command, a missing environment variable, or the app listening on the wrong port. See Troubleshooting → Deployments for the fixes.