Unraveling the Mystery of Stuck GitHub Actions Runs: A Threat to Software Engineering Quality Metrics

The Phantom Workflow: When GitHub Actions Get Stuck in Limbo

In the world of continuous integration and delivery, a smooth workflow is paramount. However, a recent discussion in the GitHub Community highlights a persistent and perplexing issue: GitHub Actions workflow runs getting stuck in a 'queued' state with zero jobs, becoming unmanageable through standard API calls. This bug not only frustrates developers but also skews critical software engineering quality metrics by perpetually showing an active, yet non-existent, process.

A Deep Dive into the Inconsistency

The core of the problem lies in a severe backend state inconsistency. A workflow run, orphaned after its definition file was removed, remained 'queued' for weeks. Despite its reported status, attempts to interact with it via GitHub's API yielded contradictory and unhelpful responses. The run's own record, as seen through the API, showed it was queued but had never expanded into jobs:

GET /repos/PyDevices/pygraphics/actions/runs/32219727413
status=queued
c
created_at=2026-08-19T05:31:17Z
updated_at=2026-08-19T05:31:17Z <- never changed
run_attempt=1

GET /repos/PyDevices/pygraphics/actions/runs/32219727413/jobs
jobs: [] <- zero jobs, ever

Further attempts to manage this run revealed a web of conflicting information:

• API Status: GET /runs/32219727413 consistently reported status: queued.
• Cancellation Attempts: Both POST /runs/32219727413/cancel and POST /runs/32219727413/force-cancel failed with a 409 error, stating the run "has not been queued yet."
• Rerun Paradox: A POST /runs/32219727413/rerun attempt was rejected with a 403, claiming "This workflow is already running."
• Deletion Blocked: DELETE /runs/32219727413 returned a 403, indicating "Could not delete the workflow run," implying it needs to be completed first—a state it cannot reach.
• CLI Contradiction: Even the gh run cancel command reported, "Cannot cancel a workflow run that is completed."

These mutually exclusive responses clearly point to a platform-side issue rather than a user misconfiguration.

The Genesis of the Glitch: A Workflow Orphaned

The specific incident originated when a commit deliberately removed the workflow definition file (.github/workflows/docs.yml) while a run of that workflow was already in the queue. This orphaned the run, trapping it in an unresolvable state.

Efforts to Resolve: What Didn't Work

The author of the discussion, bdbarnett, undertook several troubleshooting steps, all to no avail:

• Restoring the workflow definition temporarily made the workflow active again but did not release the stuck run.
• Fresh dispatches of the restored workflow completed successfully, confirming the definition itself was not the issue.
• Using gh run delete via the CLI yielded the same 403 error as the direct API call.
• The issue was isolated to this single run within the organization and could not be reproduced on demand.

A Recurring Nightmare for Engineering Team Metrics

This isn't an isolated incident. The discussion highlights a recurring class of bugs, with several other reports mirroring the same pattern of a stuck run, zero jobs, and contradictory API responses. Such persistent issues directly impact engineering team metrics, making it difficult to accurately assess CI/CD health and throughput. Examples include:

• Discussion #202511 — stuck Pages re-run, cancel returns 409
• Discussion #204118 — Pages workflow stuck queued; cancel, force-cancel (409) and delete (403) all fail
• Discussion #202969 — permanently stuck queued, cancellation returns HTTP 500
• Discussion #196717 — Actions / Pages workflows stuck queued, cannot be cancelled
• Discussion #135366 — "Cannot cancel a workflow re-run that has not yet queued"
• Discussion #51458 — stuck queued over 24h, cannot cancel

The Impact on Performance Dashboard Metrics and Developer Productivity

While the immediate impact on a single project might be low, a perpetually active, unresolvable run can significantly skew performance dashboard metrics and overall CI health reporting. It creates noise in monitoring systems and requires manual filtering, detracting from developer productivity. The lack of a user-accessible remedy means that the only path to resolution is manual intervention from GitHub support, one discussion at a time.

GitHub's Response: Acknowledgment, Not Resolution

GitHub's official response to the discussion was a generic acknowledgment of product feedback submission, promising review and cataloging by product teams. While appreciative, this response offers no immediate solution or workaround for users facing this specific, recurring platform inconsistency.

Conclusion: A Call for User-Accessible Solutions

The recurring nature of this 'phantom workflow' bug highlights a critical need for GitHub to implement a robust, user-accessible mechanism to clear or force-delete workflow runs that enter such an inconsistent state. Ensuring the accuracy of software engineering quality metrics and maintaining developer trust in platform reliability depends on addressing these fundamental issues with more than just manual, case-by-case support.