A change log turns scheduled-workflow troubleshooting from guesswork into comparison. The useful question is not only “What failed?” but “What changed between the last known-good run and the first unexpected result?” A compact record of configuration, code, credentials, dependencies, timing, and external services can narrow that interval quickly.
Freeze the evidence first
Record the workflow name, run identifier, scheduled time, actual start time, status, branch or version, triggering actor, input values that are safe to store, and the first failed step. Preserve links to logs and artifacts under the platform's normal retention rules. Do not paste tokens, private payloads, customer data, or complete environment dumps into the change log.
GitHub's workflow log guidance explains that each job and step has a status and log, failed steps can be inspected, and logs can be searched or downloaded. Use the platform's run identifiers and permanent log links when available so another reviewer can examine the same evidence.
Define the comparison window
Identify the last successful run and the first failed, missing, delayed, or incorrect run. List every relevant change made between them: workflow file commits, schedule edits, branch changes, permission updates, rotated credentials, dependency versions, runner images, data schemas, service outages, and ownership changes. Include changes that seemed unrelated. An expired credential or a renamed destination may not appear in the workflow file.
For a scheduled GitHub workflow, confirm that the file exists on the default branch, the workflow is enabled, and the schedule still targets the intended time zone. GitHub's workflow troubleshooting documentation says scheduled events run from the default branch, can be delayed during high load, and can sometimes be dropped. It also notes that a scheduled workflow can stop when the associated actor account is suspended, deleted, or deprovisioned. Those platform conditions belong in the change log even when no repository code changed.
Classify the symptom before re-running
A missing run is different from a failed run. For a missing run, inspect enablement, branch, schedule syntax, actor state, and platform status. For a queued or delayed run, inspect capacity, concurrency, rate limits, and service status. For a failed run, compare the failing step, exit status, inputs, and dependency versions. For a successful run with wrong output, compare destination identifiers, filters, data versions, and post-run validation.
Write a single testable hypothesis. For example: “The schedule did not trigger because the workflow file was removed from the default branch,” or “The job lost write access after a token-permission change.” Avoid changing the schedule, token, runner, and dependency version together. Multiple simultaneous edits destroy the comparison that makes the log useful.
Test one bounded change
Prefer a manual, non-destructive run with the same version and inputs when the platform supports it. If the workflow can send messages, charge accounts, publish content, or overwrite data, use an approved dry-run target or stop for authorization. Record the exact change, tester, time, expected result, actual result, and log link.
GitHub permits authorized users to re-run workflows and jobs, but its re-run documentation notes that a re-run uses the original event's commit and ref and the privileges of the original triggering actor. That means a re-run is not always a test of today's code or permissions. Record whether the test was a re-run, a manual dispatch, or a new scheduled occurrence.
Close the log with a verified result
A resolved entry should include the confirmed cause, repair, validation evidence, remaining risk, and rollback. If the cause remains unknown, say so and list what was ruled out. Restore any temporary debug logging and remove test-only privileges.
Over time, review repeated causes. Several credential-expiry incidents suggest a monitoring gap; several start-of-hour delays suggest schedule placement should be reconsidered; repeated unauthorized changes suggest access control needs attention. The change log is valuable when it records evidence and decisions, not when it becomes a diary of untested guesses.
Sources
- Using workflow run logs — GitHub Docs
- Troubleshooting Workflows — GitHub
- Re-running workflows and jobs — GitHub