Field notes · astro

Making scheduled static-site publishing reliable

Reliable scheduled publishing needs 6 separate checks from cron configuration to the live page, plus logs and a safe manual rebuild path for recovery.

·8 min read

Scheduled static-site publishing is reliable only when I can prove each handoff: the clock fired, the hook accepted the request, the build succeeded, Astro included the due content, and the public page became reachable. A cron entry and a green unit test are necessary, but neither proves publication.

I learned this while moving this blog’s daily rebuild away from GitHub Actions. The replacement Worker was easy to test. The more important work was defining what I would inspect when a Tuesday article did not appear.

Key takeaways

  • Treat scheduling, build initiation, build success, and publication as separate states.
  • Use UTC and choose a run time that is easy to observe.
  • Keep deploy hooks secret and error messages sanitized.
  • Make rebuild requests safe to repeat before adding retries.
  • Preserve a documented manual path that uses the same production build.
  • Verify the final URL, not just the automation that should create it.

What does reliable publication actually mean?

Reliable publication means a due article becomes publicly reachable within a known window, or the failure becomes visible soon enough for a manual recovery. It does not mean every component reports success. The outcome is the page, while the component signals explain where that outcome stopped.

I use six checkpoints:

  1. The content is eligible in repository state.
  2. The production cron is attached and due.
  3. The scheduled Worker ran.
  4. The deploy hook accepted the request.
  5. The static build completed successfully.
  6. The expected URL responds from the public site.

This separation prevents misleading conclusions. A post with draft: true is not eligible no matter how many builds run. A cron can fire while its secret is missing. A hook can return success while the build later fails. A build can complete from the wrong branch. A page can exist in build output but remain unavailable because deployment failed.

The architecture in Scheduling Astro Posts Without GitHub Actions keeps these responsibilities narrow. Astro filters content at build time, a Cloudflare Cron Worker owns the clock, and a secret deploy hook requests the normal production build.

How should I choose and test the publication clock?

Choose a UTC schedule with enough margin after the article’s date boundary, then test the same scheduled handler locally and in production. Cloudflare states in its Cron Triggers documentation that cron expressions use UTC, so local midnight assumptions can move when daylight-saving time changes.

My daily run is intentionally during a time when I can notice a problem. That turns the publication window into an operational promise: a Tuesday-dated post should be live after the first successful daily build on Tuesday. It does not promise publication at 12:00 a.m.

Cloudflare provides a way to test a scheduled handler without waiting for the real cron. I still distinguish that test from the real production event. A test proves the deployed handler can be invoked. Only the scheduled invocation log proves the cron service ran it at the expected time.

Clock testing should include four awkward cases:

  • A post dated today with draft: false.
  • A post dated tomorrow.
  • A past-dated post still marked as a draft.
  • The same production filter evaluated just before and after the boundary.

Those tests belong around the content helper, not inside the Worker. The Worker should remain unaware of Markdown or dates.

How do I make hook requests safe to repeat?

Assume a scheduler may run twice, an operator may retry manually, or a timeout may hide a successful request. Before adding automatic retries, confirm that repeating the hook creates acceptable duplicate builds and cannot publish a different branch or mutate external state beyond rebuilding the site.

Cloudflare’s Deploy Hooks documentation describes a hook as a unique URL tied to a branch. That makes the target stable, but it does not mean unlimited repeated builds are free or useful.

My first version sends one request per day and relies on the next daily run as the natural retry. This bounds the blast radius of a persistent failure. If I later add immediate retries, I will use a small count, backoff, and a clear distinction between failures that can recover and failures that require a configuration change.

For example:

Failure Retry immediately? Reason
Missing secret No Another request cannot create configuration
HTTP 401 or 403 No The hook is invalid or unauthorized
HTTP 429 Later, with backoff The platform is asking for less traffic
Temporary network error Possibly once A short transport failure may clear
Build fails after accepted hook No Worker retry Diagnose the build first

The Worker never logs the hook URL. Because the URL is the credential, even an otherwise helpful exception chain can become a secret leak.

What should be logged and alerted?

Log identifiers and outcomes that locate a failure without recording secrets: scheduled timestamp, invocation status, response status, and a correlation value if the platform provides one. Then alert on the missing outcome that matters, such as a due page still absent after the publication window.

For a once-daily personal blog, I do not need an enterprise monitoring stack. Cloudflare invocation logs and build history provide enough evidence to begin. The key is knowing which screen answers which question.

I would record or inspect:

  • The UTC time when the scheduled handler began.
  • Whether the secret binding was present.
  • Whether the request reached a success status.
  • The build start and finish time.
  • The commit and branch used for the build.
  • The expected article slug and its public response status.

The final check can be automated with a simple request after the expected build window. A 200 response does not prove the article is correct, but a 404 proves publication is incomplete. I would also check that the article appears in the blog index and feed, because route generation and discovery lists can fail independently.

This is the same lesson I applied while automating access revocation across systems: completion is not the number of commands attempted. Completion is the verified end state in every system that matters.

How should the manual fallback work?

The manual fallback should invoke the same production build path as automation, not a separate release mechanism. That keeps recovery boring: verify the local content, trigger the normal build, follow it to completion, and check the public URL.

I retained a manually dispatched workflow that calls the same secret deploy hook. If hosted CI is unavailable, I can also use the hosting platform’s normal build controls after running the local test and build commands. Neither path changes the content filter or creates an alternate artifact.

A short runbook is enough:

  1. Confirm the post is merged to the production branch.
  2. Confirm draft is false and pubDate is not in the future.
  3. Run sanitization, tests, and the Astro build locally.
  4. Trigger the normal production build once.
  5. Follow the build log until deployment completes.
  6. Request the article URL, index, and feed.

The runbook should also say when to stop. If the local build fails, do not trigger production. If the hook credential may be exposed, rotate it before retrying. If the production build uses the wrong commit, fix branch configuration rather than repeatedly requesting it.

How do repository state and live state drift apart?

Static sites can have correct repository content and stale live output because the public files only change after another successful build and deployment. Future dating makes that gap intentional for a while, which is why a status check must consider both states.

I use this simple model:

Repository state: Is the post valid, approved, and due?
Build state:      Did the correct commit produce the expected route?
Deploy state:     Did that output reach the production environment?
Live state:       Does the public URL and index show the post?

When an article is missing, I inspect from the top down. If the repository state is wrong, no infrastructure change is needed. If the Worker did not run, the clock path owns the failure. If the build failed, its log should name the content or dependency problem. If the build succeeded but the page is absent, the publication filter and deployment output deserve attention.

This layered diagnosis is faster than pressing rebuild and hoping. It also produces evidence I can use to improve the right component.

What would I monitor after the first successful run?

After the first success, I would monitor missed expected pages, unusual build frequency, repeated hook failures, and changes to the deployed cron or secret binding. One successful Tuesday proves the path once; it does not protect the configuration from later drift.

A compact recurring check can compare the content collection with the live site:

  1. Find every non-draft post whose publication date has arrived.
  2. Compute its expected public slug.
  3. Request that URL after the daily build window.
  4. Report missing pages without trying to rewrite content.

That check has a useful limit. It detects a publication gap, but it should not automatically change draft flags or merge branches. Editorial approval remains a human decision.

Frequently asked questions

The reliable version of scheduled publishing is a chain of small proofs, not a single setting that can be trusted forever.

Is a successful deploy-hook response proof that the site rebuilt?

No. It proves the build request was accepted. Inspect the build result and the public page separately.

How often should a static blog rebuild?

Use the smallest frequency that meets the publication promise. One daily build fits a weekly editorial calendar and avoids unnecessary requests.

Should the scheduler automatically clear a draft flag?

No. A draft flag represents editorial approval, not time. Automation should publish approved due content, not decide that unfinished content is ready.