---
lang: en
---

# Builds

A build is Cactus reading your connected code and writing or updating your help pages from it. While your team's plan is paused, no build starts. A page changes only after the build that covers the change finishes, and a GitHub push can wait up to a day for that build.

> Verified against the product on 2026-11-15

## Before a build starts

Connecting a repository needs a started trial, and a build has nothing to read until one is connected. Connect repositories in [Sources](https://cactus.heycactus.ai/sources), and see [Plans and billing](https://cactus.heycactus.ai/plans-and-billing) for the trial.

## Start a build

1. In [Settings › Builds](https://app.heycactus.ai/settings/builds), select **Rebuild** to have Cactus read your code again.
2. Select **Sync now** to check GitHub for pushes. If GitHub has nothing new, no build starts; if it has, a build starts, or waits behind the build already running.

> **Note:** While a build runs, **Rebuild** reads **Building now**, and both buttons are off until it finishes.

*Where Rebuild and Sync now sit*

Settings › Builds

- **Rebuild** (1)
- **Sync now** (2)

## Build status lines

| What you see | What it means |
| --- | --- |
| **Up to date with GitHub** | GitHub has no push waiting for a build. |
| Pushed _a time ago_ (_a commit_), waiting for the next build | A push is waiting for its build. |
| Pushed _a time ago_ (_a commit_), building now | A build is running with that push. |
| Next build at _a time_ UTC: _a number_ pushes waiting | The build that will take the waiting pushes, and how many there are. Shown only while no build runs. |
| Last synced _a time ago_. GitHub pushed _a time ago_. | When Cactus last checked GitHub, and when GitHub last got a push. |
| _A number_ of the last _a number_ builds succeeded. | The result of the most recent builds, up to twenty. |

## What starts a build

- **Setup**: the first build, started when you save your repositories during setup.
- **You**: a build started by **Rebuild** or **Sync now**, or by saving a change to your repositories.
- **GitHub push**: a build started by a push to a connected repository.

## When a GitHub push builds

A push starts a build at once when no build started by a push ran in the last 24 hours. Otherwise it waits until 24 hours after the last one started.

Every push that arrives before that time is built together in one run.

## Runs

The Runs list groups runs under five filters, and the last twenty builds show as bars with a count of how many succeeded.

- **Builds**: runs that build your pages.
- **Code updates**: runs started by a push to your code.
- **Writing rules**: runs that apply your writing rules to pages.
- **Investigations**: runs started by a question or an investigation.
- **Daily checks**: the daily check of your code.

A run shows as running, ready, failed or skipped. A run that a rebuild from scratch shows is marked **Rebuilt from scratch**, and each writing rule that shaped a run is listed under it, linked to [Settings › Writing](https://app.heycactus.ai/settings/writing).

## Changelog entries

A build also writes the changelog entries for the commits it reads.

An entry waits until Cactus has read the repository's full history, which can finish after the pages have changed, so an entry can show after its pages.

## If your plan is paused

While your team's plan is paused, no build starts, and **Rebuild** and **Sync now** stay off.

Pushes still arrive and wait until the plan is back, and the Builds section shows a line saying the plan is paused. An owner is pointed to a plan, see [Plans and billing](https://cactus.heycactus.ai/plans-and-billing); once a plan is chosen, the controls work again.

## Rebuild from scratch

Only an owner can rebuild from scratch, and a repository must be linked first.

The owner confirms with the product's exact name. A build still running is stopped before the rebuild starts.

## If a build fails

| What you see | What it means | What to do |
| --- | --- | --- |
| "Cactus could not finish your pages" | The first build failed before any page was written. | Select **Try again** to start it again. Select **See why** to read the cause on [Settings › Builds](https://app.heycactus.ai/settings/builds). |
| A run marked as "stopped before it finished" | The run ended before it finished, such as when a rebuild from scratch stopped it. | Select **Rebuild** to read the code again. |
| _A number_ of _a number_ pages are missing (_the reasons_); the next build writes them | Some pages the build planned were not written, so the run is marked failed | Nothing to do: the next build writes the missing pages, even when your code has not changed. Select **Rebuild** to start it now. |
| "Cactus could not confirm the build started. Press again: it will not start a second one." | The press got no clear answer from the server. | Press the same button again. A second build does not start. |