Builds
Builds reads a product’s connected repositories and writes its help pages and weekly changelog, and it lists every run in Settings › Builds. Open it to see what a build changed, press Sync now or Rebuild, or find out why builds have stopped.
On this page
Run a build now
In Settings
Control | What it does | When it is off |
|---|---|---|
Sync now | What it does Reads GitHub and starts a build only if there is something new to build. If a build is running and pushes are waiting, the build is queued behind it. | When it is off While a build is running or Cactus is paused. |
Rebuild | What it does Starts a whole build, which reads every connected repository. While it runs, the button reads Building now. | When it is off While a build is running or Cactus is paused. |
After Sync now, the page says one of these lines, and changes nothing else: "Syncing with GitHub now.", "Queued. It will sync as soon as the running build finishes.", "A build is already running.", "Waiting for the first build before it can sync.", or "Already up to date with GitHub.". Each can add ", with the push waiting" or ", with the N pushes waiting".
A build needs a connected repository. Without one, the press answers "Link a repository before you build."
Rebuild from scratch
Only an owner can rebuild from scratch. In the Danger zone of Product settings, select Rebuild from scratch, type the product’s name, and select Rebuild from scratch again to confirm.
A rebuild from scratch cancels a running build first. Your published pages stay up until each one is rewritten. Conversations, settings, and imports are kept.
When a push starts a build
A push to a connected repository is recorded and waits for a build. Until the product has a build that finished ready, every build is a whole build, so the first push starts one.
After that, waiting pushes are built at most once a day. If no push build started in the last 24 hours, the build starts at once. Otherwise it is booked for 24 hours after the last one started.
The page shows the booking as Next build at a time, with the number of pushes waiting. Above the runs it shows the GitHub state: Pushed X ago (sha), waiting for the next build, or Up to date with GitHub.
When builds stop
While Cactus is paused, nothing new starts: Sync now and Rebuild are off, and the page says "Cactus is paused, so nothing new starts." An owner sees Choose a plan, which opens the plan page to turn Cactus back on. A member sees the same line with a note of who turns it back on. Pushes that arrive while paused are kept and not built.
The plan and its limits are set out in Plans and billing.
Reading the runs
Each run appears under one of five filters, and Builds is the one shown first.
Filter | What it holds |
|---|---|
Builds | What it holds Whole builds of the help pages. |
Code updates | What it holds Runs started by pushed code. |
Writing rules | What it holds Runs started by a change to a writing rule. |
Investigations | What it holds Runs started by a question or an investigation. |
Daily checks | What it holds Daily re-reads of the product. |
A filter with no runs reads "No {filter} yet" and the line "Rebuild when you want Cactus to read the code again."
Each run is one of four outcomes, shown as a label.
Skipped runs say why in their note. Examples are "the product’s changelog is turned off" and "the build wrote no changelog". A run that is still going shows Building, with its phase beside it.
Select a run to see its summary, its pushes, any pages that failed, its note, and its run id. A run shaped by a writing rule lists that rule, and a run from scratch reads "Rebuilt from scratch".
A run can be cancelled only while it is running. Cancel it with Cancel build on Writing rules, which reads "Canceled the build." or "No build is running.".
The page also shows an activity grid of runs a day over the last 12 weeks, marking the failed days, and a build-time chart of the latest builds. Its caption reads, for example, "3 of the last 4 builds succeeded."
Help site update emails
Only a verified owner of the team sees the Help site updates panel, and each owner chooses their own setting.
Choice | What you get |
|---|---|
Daily | What you get One email for each day that a build changed the help site. This is the default. |
Weekly | What you get One email for each week in which a build changed the help site. |
Off | What you get No email. |
The email lists the pages added, rewritten, or removed, and the changelog entries released. No email goes out for the first ready build. Emails start with the second.
If a build fails
What you see | What it means | What to do |
|---|---|---|
A Failed run, with page names in red | What it means Some pages did not write. The other pages stay published, and the failed page is written again alone in a run of its own. | What to do Nothing to do: the page is written again. |
A Failed run, with the note "Stopped before it finished" | What it means The run ended before it finished. | What to do Select Rebuild. |
"Cactus couldn’t confirm the build started. Press again: it won’t start a second one." | What it means The press may or may not have started a build. | What to do Press again. Pressing again does not start a second build. |
"Cactus couldn’t start the build. Try again." | What it means The build was refused. | What to do Press again. |
A product’s first build is tried once more by Cactus if it fails. If that retry fails too, the run stays Failed.