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 SettingsBuilds, select Sync now or Rebuild. Any member of the team can press either.

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.

The outcomes a run can end with, as the Builds list labels them.

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.

Sources

Related pages