Pausing a GitHub Actions cron: the yaml trap that breaks all workflow triggers

#githubactions #tutorial #webdev #programming

After 11 uploaded videos disappeared from YouTube overnight, I wanted to stop the automated upload schedules while I investigated. The fix seemed trivial: comment out the cron lines in two workflow files. I've done this before without thinking about it. Today it broke two unrelated things.

Here's what went wrong and how to pause a cron correctly.

The mistake: commenting out the cron line but leaving the key

The original yt-publish.yml looked like this:

on:
  push:
    branches: [main]
  schedule:
    - cron: '0 21 * * 1,3,5'

My first attempt at pausing was:

on:
  push:
    branches: [main]
  schedule:
    # - cron: '0 21 * * 1,3,5'

That leaves schedule: as a key with no value. In YAML terms, schedule: with no value is a null scalar, which is valid YAML — but GitHub Actions doesn't accept it. Its workflow schema requires schedule to be a sequence. An empty schedule: key fails validation.

I did the same thing in yt-publish-longform.yml. Two workflows now in a broken state.

How the failure shows up

The cryptic part: the error doesn't say "invalid schedule". GitHub's runner rejects the whole workflow file and the failure appears on every trigger, including push.

The Actions tab shows:

Run status: failed
Run duration: 0s
Message: "This run likely failed because of a workflow file issue."

At 0s, no job has started. It's a pre-parse failure. Because both affected workflows had a push trigger as well as schedule, every commit to main for the next hour showed red checks. The failing workflow was the upload pauser, not any of the actual build or publish workflows — so at first the red commits looked related to something I'd pushed, not to the yaml edit.

The tell: 0s duration. Any real job failure takes at least a few seconds to allocate a runner. A 0s failure almost always means the workflow file didn't parse.

The fix: comment out the entire schedule key

The correct way to pause a cron without disabling other triggers is to comment out the key itself. GitHub's workflow syntax docs require schedule to be a non-empty sequence — an empty mapping key fails schema validation.

on:
  push:
    branches: [main]
  # schedule:   # ⚠ PAUSED 2026-08-11 — uncomment this line AND the cron line below to resume
  #   - cron: '0 21 * * 1,3,5'

With schedule: itself commented out, the on: block only contains push. GitHub parses this without complaint. The push trigger still fires; manual workflow_dispatch calls still work.

I also added a note in the comment explaining why it's paused and exactly which line to uncomment. This is worth the extra characters — "uncomment to resume" comments have saved me from re-investigating why a schedule was disabled when I come back to it two weeks later.

The useful side effect: workflow_dispatch still works

When only schedule is disabled, workflow_dispatch remains active. This turned out to be exactly what I needed: I could test the disappearance detection code by triggering the analytics workflow manually from the Actions tab, without the risk of automatically uploading more videos to a channel with unexplained deletions.

There's a common pattern where pausing a cron is paired with needing manual testing:

Something went wrong with the automated run
You want to stop the automation while you debug
But you want to run it once manually to verify a fix

workflow_dispatch covers this exactly. Commenting out schedule while leaving workflow_dispatch gives you manual control without re-enabling the automation.

Relevant to four cron timing bugs I've hit before: this is the opposite problem — not a cron that fires at the wrong time, but a cron that needs to stop while preserving manual access. The yaml trap is easy to avoid once you've seen it, but the failure mode is confusing enough the first time that it's worth writing down.

Summary

What you do	What GitHub sees	What breaks
Comment out just the cron line	`schedule:` with null value	Whole workflow fails (0s) on all triggers
Comment out the `schedule:` key	Valid `on:` with only remaining triggers	Nothing — push and workflow_dispatch still work
Remove `schedule:` key entirely	Same as above	Nothing

The second and third rows are equivalent. I prefer commenting over deleting because it preserves the cron expression for when I want to re-enable, and the "PAUSED" comment documents the decision.

Part of an ongoing 6-month experiment running three AI-curated directory sites. The technical claims here are real; this article was AI-assisted.