> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bellows.cloud/llms.txt
> Use this file to discover all available pages before exploring further.

# Quickstart

> Connect a repo, describe a change, review the pull request Bellows opens.

## Before you start

* A GitHub repository you can install apps on
* Commands that build and test it (we'll use `make build` and `make test`)

The examples use a small Go web server with lorem ipsum and notes endpoints. Any language works.

## Steps

**1. Sign in and choose repositories**

Sign in with GitHub, install the Bellows GitHub App, then choose the organizations and repositories Bellows should track.

![Onboarding: choose organizations and repositories](https://mintcdn.com/bellows/F3bOEtFaYdaW9xJ2/images/quickstart/01-onboarding.png?fit=max\&auto=format\&n=F3bOEtFaYdaW9xJ2\&q=85\&s=1199db43d967ae67f50c8d3a458a20a6)

**2. Check the repository is tracked**

Open **Settings → Repositories**. Your repo is listed there, and **Configure** shows its environment.

![Settings, Repositories](https://mintcdn.com/bellows/F3bOEtFaYdaW9xJ2/images/quickstart/02-settings-repos.png?fit=max\&auto=format\&n=F3bOEtFaYdaW9xJ2\&q=85\&s=15ce4f2eca4bce89e3760f21f127124d)

**3. Add .bellows.yaml to the repo root**

This file sets the runner's container and the checks every run must pass.

```yaml .bellows.yaml theme={null}
environment:
    image: golang:1.25
    setup: "go mod download"
    gates:
        - name: build
          command: "make build"
          timeout: 5
        - name: test
          command: "make test"
          timeout: 10
```

Commit and push it to the default branch.

**4. Create a task**

Click **New task**. Under *What should we work on?* describe the change, pick the repo and executor, then click the arrow (**Start task**) or press `⌘ + Enter`.

```text Task theme={null}
Add a GET /api/notes/count endpoint that returns {"count": N}.
Add a table test in internal/server/server_test.go.
```

![New task form](https://mintcdn.com/bellows/F3bOEtFaYdaW9xJ2/images/quickstart/03-new-task.png?fit=max\&auto=format\&n=F3bOEtFaYdaW9xJ2\&q=85\&s=26e71a6cbf3b0c07f808512c778f20dc)

**5. Answer questions, if any**

Some tasks need a decision from you. The agent asks inline and waits. Pick an answer and click **Submit**.

![Agent question waiting for an answer](https://mintcdn.com/bellows/F3bOEtFaYdaW9xJ2/images/quickstart/04-question.png?fit=max\&auto=format\&n=F3bOEtFaYdaW9xJ2\&q=85\&s=f7030e5bbff5bdd55d18efe8fff051f1)

**6. Review and finish**

Once the gates pass, Bellows opens a pull request and the task shows Waiting for review. Review the PR on GitHub. If it needs changes, use **Follow up** on the task. Once it's merged, click **Mark done**.

![Task waiting for review with a published pull request](https://mintcdn.com/bellows/F3bOEtFaYdaW9xJ2/images/quickstart/05-task-review.png?fit=max\&auto=format\&n=F3bOEtFaYdaW9xJ2\&q=85\&s=29948d8c3308098ca589587163b5dc3c)

The task page: conversation and follow-up on the left; outcome, verification and the published PR on the right.

## What just happened

Queued → Running → Gates: build, test → Waiting for review → Done

The driver started a `golang:1.25` runner and ran `setup`. Then the agent made the change. Bellows ran each gate, and the PR opened only after all of them passed.

> [!TIP]
>
> Writing a good task description is the biggest lever on results. See [Writing good tasks](https://docs.bellows.cloud/guides/writing-good-tasks.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.