---
title: "Quickstart: set up Stagely for your team"
description: "Set Stagely up once: sign up, subscribe, link GitHub, set up your cloud, add .stagely.yml, a project and config, then open a pull request to get a stagelet."
url: https://stagely.dev/docs/setup
---

This page is for the person who sets Stagely up for the team. You create the account, so you are its owner. At the end, every new pull request in your repository gets a stagelet without any manual step.

## Before you start

You need:

- Repositories on GitHub, and the right to install a GitHub App on the user or organization that owns them.
- An app that runs with Docker Compose, within the [Compose rules](https://stagely.dev/docs/app/compose.md).
- An account on DigitalOcean, AWS, Google Cloud, Azure, Hetzner Cloud or Vultr, and credentials that can create resources in it. [Set up your cloud](https://stagely.dev/docs/setup/cloud.md) lists what each cloud needs.
- A domain for stagelet host names, such as `stagelets.example.com`, where you can add a DNS record.
- The public address range of the computer that runs setup. Only addresses in this range can reach your hosts over SSH.
- On that computer: the `stagely` CLI, OpenTofu or Terraform, and the `stagely-agent` and `stagely-gateway` binaries for linux/amd64 in one directory. Each [release](https://github.com/stagely-dev/stagely/releases) has an archive of all three for your computer and one for linux/amd64, with checksums.

## 1. Create the account

Open the Stagely console. Click **Continue with GitHub**. Give the account a name, such as your company's name. Click **Create account**. You are now its owner.

## 2. Subscribe

Open **Billing**. Choose **Monthly** or **Annual**, then click **Subscribe to** a plan to open Stripe Checkout. The first subscription starts with a 14-day trial, and Checkout asks for no card. When you finish checkout, the console shows that the account can deploy. Without a subscription, Stagely refuses deploys and says why. [Plans and billing](https://stagely.dev/docs/setup/billing.md) compares the plans.

## 3. Link GitHub

Open **Projects**. Click **Link GitHub**. Choose the user or organization that owns your repositories. Install the Stagely GitHub App on it. The console then shows the installation as linked.

The App asks for these repository permissions: read contents and metadata, write pull requests (to reply to deploy commands) and write commit statuses (to show each deploy on the pull request). It receives pull request and issue comment events.

## 4. Set up your cloud

On your computer, sign the CLI in to Stagely. Then run setup for your cloud. This example uses DigitalOcean.

```sh
export DIGITALOCEAN_TOKEN=<token>
stagely login
stagely setup digitalocean \
  -environment production \
  -region fra1 \
  -stagelet-domain stagelets.example.com \
  -registry example-stagely \
  -operator-cidr 203.0.113.7/32 \
  -binaries bin/linux-amd64 \
  -acme-email ops@example.com
```

`stagely login` opens a consent page in your browser. Click **Allow**. Setup then creates the network, the agent host, the gateway host, their firewalls and a container registry. After that, it installs the agent and the gateway, and enrolls them.

At the end, setup prints the gateway's address. Point `*.stagelets.example.com` at it with an A record.

**Check:** in the console, open **Environments**, then your environment. Under **Connection**, the agent and the gateway show **Connected**.

[Set up your cloud](https://stagely.dev/docs/setup/cloud.md) has the steps and flags for every cloud.

## 5. Add `.stagely.yml` to the repository

Commit a `.stagely.yml` to the root of your repository. It names your Compose files, the service people open, its health check and an optional migration:

```yaml
version: 1
compose:
  - deploy/compose.yml
public:
  service: web
  port: 8080
health:
  path: /healthz
migration:
  command: bin/rails db:migrate
```

Stagely reads it from each pull request's head commit. See [.stagely.yml](https://stagely.dev/docs/app/stagely-yml.md) for every field.

## 6. Create the project

In **Projects**, click **New project**. Choose the repository and the environment. Click **Create project**.

The defaults suit most teams: new pull requests and pushes deploy, the comment command is `/stagely`, label deploys are off, and Stagely deletes a stagelet 72 hours after its last deploy. [Deploys from pull requests](https://stagely.dev/docs/app/deploys.md) explains each setting.

## 7. Add config

In the project's **Config**, add the plain values that your app needs. For each secret, add a secret reference here. Then store the value on the agent host. [Config values and secrets](https://stagely.dev/docs/setup/config.md) shows the commands.

## 8. Open a pull request

Push a branch. Open a pull request from it. In the console, open **Stagelets**. The pull request's stagelet appears there with the state **Deploying**. Click the stagelet to open its page. The page shows the steps and logs live. When the page shows **Running**, click **Open** on that page.

On GitHub, the pull request shows a `stagely/<account>` commit status. Its **Details** link opens the stagelet's page in the console.

## Next

- [Invite your team](https://stagely.dev/docs/setup/team.md).
- [Connect a coding agent](https://stagely.dev/docs/agents.md), so it can deploy and test its own pull requests.
- Read the [security model](https://stagely.dev/docs/security.md) before you add real secrets.