diff --git a/content/actions/reference/workflows-and-actions/index.md b/content/actions/reference/workflows-and-actions/index.md index f3bac90f6946..03e265987d3e 100644 --- a/content/actions/reference/workflows-and-actions/index.md +++ b/content/actions/reference/workflows-and-actions/index.md @@ -3,9 +3,9 @@ title: Workflows and actions reference shortTitle: Workflows and actions intro: Find information on workflows and actions in GitHub Actions. versions: - fpt: '*' - ghes: '*' - ghec: '*' + fpt: "*" + ghes: "*" + ghec: "*" children: - /workflow-syntax - /events-that-trigger-workflows @@ -18,7 +18,7 @@ children: - /reusing-workflow-configurations - /metadata-syntax - /workflow-cancellation + - /workflow-run-statuses - /dockerfile-support contentType: reference --- - diff --git a/content/actions/reference/workflows-and-actions/workflow-run-statuses.md b/content/actions/reference/workflows-and-actions/workflow-run-statuses.md new file mode 100644 index 000000000000..ac88d45d7dda --- /dev/null +++ b/content/actions/reference/workflows-and-actions/workflow-run-statuses.md @@ -0,0 +1,52 @@ +--- +title: Workflow run statuses and conclusions +shortTitle: Workflow run statuses +intro: Learn how status and conclusion values describe the lifecycle and result of a workflow run. +versions: + fpt: "*" + ghes: "*" + ghec: "*" +category: + - Manage and monitor workflow runs +contentType: reference +--- + +A workflow run has a `status` while it moves through its lifecycle. When the run finishes, it has a `conclusion`. + +The workflow run list endpoints in the REST API use the `status` query parameter for both status values and conclusion values. For more information, see [AUTOTITLE](/rest/actions/workflow-runs). + +## Status values + +Use `status` to understand what phase the workflow run is in. + +| Status | Meaning | Typical use case | +| ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- | +| `requested` | The run has been created, but it has not been added to the queue yet. This value is set only by {% data variables.product.prodname_actions %}. | The event that triggered the workflow has been accepted, and the run is about to be scheduled. | +| `queued` | The run is in the queue and is waiting to be scheduled. | {% data variables.product.prodname_actions %} has not started running the workflow yet. | +| `pending` | The run is blocked by concurrency limits. This value is set only by {% data variables.product.prodname_actions %}. | Another job or workflow in the same concurrency group is already in progress. | +| `waiting` | The run is paused until a deployment protection rule is satisfied. This value is set only by {% data variables.product.prodname_actions %}. | A job is waiting for a required review or another environment gate. | +| `in_progress` | At least one part of the run is actively executing. | A runner has started processing the workflow. | +| `completed` | The run has finished. When a run reaches this state, it also has a `conclusion`. | The workflow ended with a final result. | + +## Conclusion values + +Use `conclusion` to understand the final result after a workflow run is `completed`. + +| Conclusion | Meaning | Typical use case | +| ----------------- | ------------------------------------------------------------ | ------------------------------------------------------------------------------- | +| `success` | The run finished successfully. | All required work completed as expected. | +| `failure` | The run finished with a failure. | A step or job reported an error. | +| `neutral` | The run finished without a success or failure result. | The workflow completed, but it did not produce a pass/fail outcome. | +| `cancelled` | The run stopped before it finished. | Someone canceled the run, or concurrency canceled an older run. | +| `timed_out` | The run exceeded an allowed time limit. | A job or run took too long to finish. | +| `action_required` | The run completed, but additional action is still needed. | A manual or external follow-up is required before work can continue. | +| `skipped` | The run's work was skipped. | Conditions prevented jobs or steps from running. | +| `stale` | {% data variables.product.github %} marked the run as stale. | The run stayed unresolved long enough that it was no longer treated as current. | +| `startup_failure` | The run failed during startup. | Initialization failed before the run could proceed normally. | + +## Notes + +- `requested`, `pending`, and `waiting` are set only by {% data variables.product.prodname_actions %}. +- `pending` commonly appears when you use [AUTOTITLE](/actions/how-tos/write-workflows/choose-when-workflows-run/control-workflow-concurrency). +- `waiting` commonly appears when a job is blocked by [AUTOTITLE](/actions/how-tos/deploy/configure-and-manage-deployments/review-deployments) or other deployment protection rules. +- `startup_failure` can appear as a workflow run conclusion in webhook payloads, even though it is not an accepted `status` filter value for the REST API list endpoints. diff --git a/content/rest/actions/workflow-runs.md b/content/rest/actions/workflow-runs.md index 9ef11019b797..cc4abc8b18aa 100644 --- a/content/rest/actions/workflow-runs.md +++ b/content/rest/actions/workflow-runs.md @@ -6,9 +6,9 @@ intro: >- Use the REST API to interact with workflow runs in {% data variables.product.prodname_actions %}. versions: # DO NOT MANUALLY EDIT. CHANGES WILL BE OVERWRITTEN BY A 🤖 - fpt: '*' - ghec: '*' - ghes: '*' + fpt: "*" + ghec: "*" + ghes: "*" autogenerated: rest category: - Automate CI/CD workflows @@ -16,6 +16,6 @@ category: ## About workflow runs in {% data variables.product.prodname_actions %} -You can use the REST API to view, re-run, cancel, and view logs for workflow runs in {% data variables.product.prodname_actions %}. {% data reusables.actions.about-workflow-runs %} For more information, see [AUTOTITLE](/actions/managing-workflow-runs). +You can use the REST API to view, re-run, cancel, and view logs for workflow runs in {% data variables.product.prodname_actions %}. {% data reusables.actions.about-workflow-runs %} For reference information about `status` and `conclusion` values, see [AUTOTITLE](/actions/reference/workflows-and-actions/workflow-run-statuses). For more information, see [AUTOTITLE](/actions/managing-workflow-runs).