From 1509b28e5dad6478ff534131c39719ef0904ea1f Mon Sep 17 00:00:00 2001 From: BM Cho Date: Fri, 17 Jul 2026 17:40:46 +0800 Subject: [PATCH] docs: document workflow run statuses --- .../reference/workflows-and-actions/index.md | 1 + .../workflow-run-statuses.md | 47 +++++++++++++++++++ content/rest/actions/workflow-runs.md | 2 +- 3 files changed, 49 insertions(+), 1 deletion(-) create mode 100644 content/actions/reference/workflows-and-actions/workflow-run-statuses.md diff --git a/content/actions/reference/workflows-and-actions/index.md b/content/actions/reference/workflows-and-actions/index.md index f3bac90f6946..5fd4e6382919 100644 --- a/content/actions/reference/workflows-and-actions/index.md +++ b/content/actions/reference/workflows-and-actions/index.md @@ -18,6 +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..9c1512e79d1f --- /dev/null +++ b/content/actions/reference/workflows-and-actions/workflow-run-statuses.md @@ -0,0 +1,47 @@ +--- +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. After the run reaches a `completed` status, its `conclusion` describes the final result. + +The workflow run list endpoints in the REST API use the `status` query parameter to filter by either status or conclusion. For more information, see [AUTOTITLE](/rest/actions/workflow-runs). + +## Status values + +| Status | Description | +| --- | --- | +| `requested` | The workflow run was created but has not been queued. | +| `queued` | The workflow run is queued. | +| `pending` | The workflow run is at the front of the queue, but a concurrency limit has been reached. | +| `waiting` | The workflow run is waiting for a deployment protection rule to be satisfied. | +| `in_progress` | The workflow run is in progress. | +| `completed` | The workflow run completed and has a conclusion. | + +Only {% data variables.product.prodname_actions %} can set the `requested`, `pending`, and `waiting` statuses. + +For more information about the conditions that cause `pending` and `waiting` statuses, see [AUTOTITLE](/actions/how-tos/write-workflows/choose-when-workflows-run/control-workflow-concurrency) and [AUTOTITLE](/actions/how-tos/deploy/configure-and-manage-deployments/review-deployments). + +## Conclusion values + +| Conclusion | Description | +| --- | --- | +| `action_required` | The workflow run completed and requires action. | +| `cancelled` | The workflow run was cancelled before it completed. | +| `failure` | The workflow run failed. | +| `neutral` | The workflow run completed with a neutral result. | +| `skipped` | The workflow run was skipped. | +| `stale` | The workflow run was marked stale by {% data variables.product.github %}. | +| `success` | The workflow run completed successfully. | +| `timed_out` | The workflow run timed out. | +| `startup_failure` | The workflow run failed during startup. | + +The `startup_failure` value can appear as a workflow run conclusion in webhook payloads. It is not an accepted value for the `status` query parameter in the REST API workflow run list endpoints. diff --git a/content/rest/actions/workflow-runs.md b/content/rest/actions/workflow-runs.md index 49e75ba4cf94..279d54a306a5 100644 --- a/content/rest/actions/workflow-runs.md +++ b/content/rest/actions/workflow-runs.md @@ -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/how-tos/manage-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/how-tos/manage-workflow-runs).