Unraveling GitHub Actions 404s: The Case of Reusable Workflows and API Triggers

A Puzzling Regression in GitHub Actions Workflow Retrieval

In the realm of automated software development planning and execution, GitHub Actions plays a pivotal role. However, a recent community discussion highlighted a peculiar regression impacting how developers interact with reusable workflows, specifically when triggered via API or the gh CLI. This issue, observed on GitHub Enterprise instances, manifests as a 404 "suffixed values" error when attempting to retrieve details of an API-triggered workflow run, even though the workflow itself appears to start successfully.

The Setup: Reusable Workflows and Relative Paths

The core of the problem lies in a common and logically sound workflow configuration. Consider a scenario with two workflows in the same repository:

• Workflow A: A reusable workflow designed to be called by other workflows.

name: Workflow A
on: workflow_call:
  jobs:
    // some job goes here

• Workflow B: A workflow triggered by workflow_dispatch that reuses Workflow A using a relative path.

name: Workflow B
on: workflow_dispatch:
jobs:
  workflowA:
    uses: ./.github/workflows/workflowA.yml

This setup works flawlessly when Workflow B is triggered directly from the GitHub UI, demonstrating the logical correctness of the configuration.

The Issue: API/CLI Triggering and the Elusive 404

The problem arises when Workflow B is triggered using the GitHub API or the gh CLI. While the workflow run initiates successfully and appears in the GitHub UI, any subsequent attempt to retrieve details of that specific API-triggered run results in a 404 error:

Response 404 {"message":"Unable to complete request that contains suffixed values in the response payloads."}

This behavior is particularly perplexing because the same setup was functioning correctly until recently, indicating a regression. Such unexpected changes can significantly disrupt a well-defined software development project plan that relies on API automation.

The Workaround: Embracing Absolute References

A critical observation by the community member PuneetDwivediDnb revealed a straightforward workaround: replacing the relative reference to Workflow A with an absolute reference in Workflow B. When the uses statement is modified as follows, the issue disappears, and API-triggered runs can be retrieved without error:

name: Workflow B
on: workflow_dispatch:
jobs:
  workflowA:
    uses: owner/repo/.github/workflows/workflowA.yml@ref # changed here to full import

This suggests a change in how GitHub Actions (specifically on GitHub Enterprise) resolves relative paths for reusable workflows when the parent workflow is triggered via API/CLI.

Expert Insights and Best Practices for Robust Workflows

Community expert Tsknefe provided valuable context, explaining that 404 responses in such scenarios often stem from incorrect resolution of the workflow identifier. Key points include:

• Correct Workflow Identifier: Ensure the API references the workflow file name (e.g., workflow_a.yml), not the name: field defined within the YAML.
• Target Ref Presence: The workflow file must exist on the branch (ref) specified in the API request.
• Direct Dispatch Limitations: Workflows with only on: workflow_call: cannot be dispatched directly via the REST API. They require a parent workflow_dispatch workflow.
• Repository Path Resolution: Always use the correct, fully qualified path for reusable workflows: owner/repo/.github/workflows/workflow.yml@ref.

The most stable pattern for integrating API triggers with reusable workflow logic is: API → workflow_dispatch → parent workflow → workflow_call reusable workflow. This separation ensures that the API trigger interacts with a dispatchable workflow, which then internally manages the call to reusable components.

Conclusion: Strengthening Your Software Development Planning

This incident underscores the importance of understanding the nuances of GitHub Actions, especially when integrating with APIs and using advanced features like reusable workflows. While relative paths offer convenience, relying on absolute paths for reusable workflows, particularly in API-driven contexts, appears to be a more robust approach following this regression. By adhering to best practices and staying informed about platform changes, developers can ensure their automated software development planning remains resilient and efficient, even in the face of unexpected platform behavior.