# Deploy on Hangar button

Add a button to your README that lets anyone deploy your repository on Hangar in one click.

The Deploy on Hangar button turns a public repository into a one-click deploy. Whoever clicks it lands on a page that names the repository, lets them pick a region and starts the deploy in their own account.

It suits open source projects, templates and example apps.

## The link

The button is a link to `/deploy` with the repository's address:

```text
https://tryhangar.io/deploy?repo=https://github.com/owner/name
```

| Parameter | Required | Meaning |
|---|---|---|
| `repo` | Yes | The public `https` URL of the repository |
| `branch` | No | The branch to deploy. Defaults to `main` |
| `dir` | No | The folder the app lives in, such as `apps/web` in a monorepo. Defaults to the root |

The repository must be public and reachable over plain `https`. Links that carry credentials, another protocol or a query string are refused.

## Add it to a README

```markdown
[![Deploy on Hangar](https://tryhangar.io/deploy-on-hangar.svg)](https://tryhangar.io/deploy?repo=https://github.com/owner/name)
```

Replace `owner/name` with your repository.

## What happens on click

1. The visitor sees the repository and signs in or creates an account. They come straight back to the deploy afterwards.
2. They choose a name, a branch and a region.
3. Hangar creates a project with one service, gives it an address with HTTPS, builds the repository with the automatic builder and deploys it. A repository with a [`hangar.yaml`](https://tryhangar.io/docs/hangar-yaml) gets what the file describes instead: several services, databases, volumes and variables, and the deploy page shows that plan and asks the file's questions first.

The deploy runs in the visitor's account and counts against their plan, not yours.

## Make your repository deploy cleanly

- Keep the app at the root of the repository or pass its folder in `dir`, or ship a Dockerfile.
- Read configuration from environment variables and document the ones that are required.
- Listen on `0.0.0.0`.
- Add a [`hangar.yaml`](https://tryhangar.io/docs/hangar-yaml) when the app needs a database, a volume, generated secrets or more than one service.
