---
lang: en
---

# Builds

Builds rebuild a product’s help pages and changelog from its code and sources as they change, and each build is listed as a run on Settings › Builds, with its state and what it published.
You can press **Rebuild** or **Sync now** on that screen, and see why pages changed over the last 12 weeks there too.

> Verified against the product on 2026-11-20

## Rebuild the help pages

1. In **Settings › Builds**, select **Rebuild**.
2. Cactus starts a build, which reads the code again and adds a run to the **Runs** list.

Rebuild needs at least one linked repository. Without one, Cactus answers “Link a repository before you build.” Connect one on [Sources](https://cactus.heycactus.ai/ec27z4-sources) first.

**Rebuild** is off while a build runs, when it reads **Building now**, and while Cactus is paused.

### Sync with GitHub now

Select **Sync now** to check GitHub for pushes that no build has taken yet.

Sync now answers in one of these ways:

- “Syncing with GitHub now,” with the number of pushes waiting, when a build starts.
- “Queued. It will sync as soon as the running build finishes,” when a build is already running.
- “A build is already running.” when a build is running and no push waits.
- “Waiting for the first build before it can sync.” when no build has finished yet.
- “Already up to date with GitHub.” when GitHub has no change to take.

When a build is needed, Sync now starts the same build that Rebuild starts.

## What starts a build on its own

A push to a linked GitHub repository is recorded for the next build. A build starts straight away unless a push build started in the last 24 hours; then it waits until 24 hours after that build started.

Until a product’s first build ends ready, every build is a whole build, so a push starts the first one.

While pushes wait, the page shows “Next build at” a time, then how many pushes wait.

The line under the page title says where GitHub stands:

- “Up to date with GitHub” when nothing is waiting.
- “Pushed” a time ago, with the commit, and “waiting for the next build.”
- “Pushed” a time ago, with the commit, and “building now.”

A paused product starts no build, and its pushes keep waiting until Cactus is turned back on.

## Run states

A run shows one of four states, its label in the **Runs** list:

*How a run ends*

Building · Ready · Failed · Skipped

- Building › its work finishes › Ready
- Building › a step errors or the run stops › Failed
- Building › nothing was waiting to update › Skipped

```
```

> **Note:** Skipped runs are left out of the build-time chart.

- **Building** is a run still going.
- **Ready** is a run whose work finished with nothing stopped.
- **Failed** is a run where a step errored, or where the run ended before it finished.
- **Skipped** is a run with nothing to do: “nothing was waiting to update,” or “no completed build yet; setup or Rebuild starts one.”

## What each run group holds

| Group | What it holds |
| --- | --- |
| **Builds** | Whole builds and builds of pushed code, started by setup, by **Rebuild** or **Sync now**, or by a push. |
| **Code updates** | Passes that took pushed code. |
| **Writing rules** | Passes that rewrote pages after a writing rule changed, with no push. |
| **Investigations** | Investigations and questions. |
| **Daily checks** | Daily checks. |

A build’s row names what started it: **Setup**, **You**, or **GitHub push**.

Open a run to see its page count, how long it took, the pages that failed, and its run ID.

A run that a writing rule shaped lists that rule under it, with a link to [Settings](https://cactus.heycactus.ai/h78hdn-settings). A run rebuilt from scratch reads “Rebuilt from scratch.”

## What the charts show

The activity grid counts runs a day over the last 12 weeks, and marks the days with a failed run.

The build-time chart shows the last 20 builds, and its longest bar.

Above the runs, “Why pages changed” groups the changes of the last 12 weeks by cause: code, question, rule or source.

## Help site update emails

Only a team owner sees the **Help site updates** panel, and only an owner can save a choice.

Each owner chooses **Daily**, **Weekly** or **Off** for themselves. Daily is the default.

Only owners with a verified email get these emails.

A daily email covers one UTC day, and a weekly email covers one week. It is sent when that window closes.

An email is sent only when a ready build in its window changed pages or releases. The first ready build sends none.

Each email lists pages as new, rewritten or removed.

**Off** sends no email.

## If your first build fails

If your first build fails, Cactus builds it once more on its own.

## If a build doesn’t finish

| What you see | What it means | What to do |
| --- | --- | --- |
| A run marked **Failed**, with page names under it | Those pages were not written. Other pages stay published, and Cactus writes each failed page again alone. | Wait for that pass, or select **Rebuild**. |
| “Stopped before it finished” under a run | The run ended before it finished. | Select **Rebuild**. |
| “Cactus is paused, so nothing new starts.” | The team has no plan, so no build starts. | An owner selects **Choose a plan**, which opens [Plans and billing](https://cactus.heycactus.ai/ajj6gc-plans-and-billing). Anyone else asks an owner. |
| “Cactus couldn’t confirm the build started. Press again: it won’t start a second one.” | The request may have reached Cactus, so pressing again is safe. | Press **Rebuild** or **Sync now** again. |
| “Cactus couldn’t start the build. Try again.” | The build was refused. | Press **Rebuild** again. |

> **Warning:** A build that was stopped by a person is not retried.

The [usage](https://cactus.heycactus.ai/3bdx2p-usage) page shows how many pages are kept current and what builds have run.
