Troubleshoot Shipfox Workflow Sync
Find why workflow YAML did not produce a usable definition and verify the corrected sync.
Use this guide when a workflow is missing from the Workflows tab. It also applies when the project reports Workflow sync failed.
Before you begin
You need access to the project, its source integration connection, and the repository's default branch.
Inspect the sync result
Open the project and select Workflows. Read the sync badge and failure message before changing the workflow.
| Result | What to check |
|---|---|
| No workflow files | The default branch contains .yml or .yaml files under .shipfox/workflows/ |
| Invalid definition | The named file follows the strict workflow schema and every referenced job, step, integration connection, and tool exists |
| Repository or file not found | The project still points to a repository visible through its source integration connection |
| Access denied or integration connection unavailable | The source integration is installed and authorized for the repository |
| Too large or too many files | The workflow files fit the documented limits |
| Context not available | A field reads a context that does not exist where Shipfox fills that field. See below |
Correct a context that is not available
A field can read only the contexts listed in Context availability. If it reads another context, sync fails. The error names the field, the unavailable context, and the stage where that context first exists:
Job runner interpolation references context "steps" that is not available at
job activation. "steps" becomes available at step dispatch.Correct it in one of two ways:
- Move the reference to a field that Shipfox fills later. A step
runorenvvalue can read step results thatjobs.<job_id>.runnercannot. - Carry the value forward as data. Declare a step output or a job output, then
read it through
steps,needs, orjobsin the later field.
Correct and verify
- Fix the reported problem on the repository's default branch.
- Commit and push the correction.
- Return to the Workflows tab.
- Wait for the sync badge to reach succeeded.
- Open the workflow and confirm that its source matches the committed YAML.
A successful sync changes only future runs. It does not change an active run. It also leaves earlier attempts unchanged.