# Deploy from GitHub
URL: https://openship.io/docs/guides/deploy-from-github.md

Connect a GitHub repository and put it online — the step-by-step way and the one-command way.

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

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.

<Callout title="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.
</Callout>

## Steps

<Steps>

<Step>

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

<Callout title="Self-hosted: two ways to connect (no Openship account required)" type="info">
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](/docs/guides/self-hosted-github-app).
- **Manual** — connect with your **own** GitHub identity, no Openship in the middle:
  - **`gh` CLI on the instance** — press **Log in with GitHub**; if the instance has `gh` authenticated
    it's picked up immediately, otherwise run the shown `gh auth login` on 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/device` link 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.
</Callout>

</Step>

<Step>

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

</Step>

<Step>

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

</Step>

<Step>

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

<Callout title="Tip" type="info">
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.
</Callout>

</Step>

<Step>

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

</Step>

</Steps>

## 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](/docs/guides/actions).

## CLI

Everything above works from the CLI too:

```bash
# 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 --enable
```

## Troubleshooting

<Callout title="“Connect GitHub” does nothing / no repos show up" type="warn">
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.
</Callout>

<Callout title="The build failed" type="error">
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](/docs/troubleshooting/deployments) for the fixes.
</Callout>

## Related guides

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