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

## The click-by-click way

<Steps>

<Step>

### Connect your GitHub account (once)

Openship needs permission to read your repository. You only do this one time.

Go to **Settings → General** and press **Connect GitHub**. A GitHub window pops up asking "do you allow
this?" — say yes. When it closes, you're connected.

<Callout title="Screenshot">Settings → General tab, the "GitHub" card with a **Connect GitHub** button. *(screenshot pending)*</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.

<Callout title="Screenshot">Library page, **Repositories** tab, list of GitHub repos each with an "Import"/select action. *(screenshot pending)*</Callout>

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

<Callout title="Screenshot">The live build screen showing streamed build steps and, at the end, the live URL. *(screenshot pending)*</Callout>

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

## Prefer the terminal?

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
```

## If something goes wrong

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

## What next?

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