This is an automated email from the ASF dual-hosted git repository. potiuk pushed a commit to branch main in repository https://gitbox.apache.org/repos/asf/airflow.git
commit 8ae08bb7dd890646f1c76cfd0f8bac62ee44c85f Author: Jarek Potiuk <[email protected]> AuthorDate: Sat Nov 14 09:46:37 2026 +0100 Explain fork CI runs that fail to start and link contributor docs (#76835) A fork run that ends in startup_failure (the fork's Actions settings block the workflow, or the workflow file is invalid) has no jobs and no log. The monitor reported it like any failed run, asking the author to "fix the failures", with nothing on the pull request saying what failed or where to look. Such a run now gets its own status description and state comment text that say no job ran and point to the fork's Actions settings and the run page; the pull request is otherwise handled as failed. The state comment's "How this works" and setup links point to the "CI in your fork" section of the contributor docs instead of the design document, as suggested in the AIP-120 vote thread. Generated-by: Claude Opus 5 --- contributing-docs/18_contribution_workflow.rst | 6 +++- .../doc/ci/08_fork_ci_for_external_contributors.md | 15 ++++++++-- .../src/airflow_breeze/utils/fork_ci_messages.py | 35 ++++++++++++++++++---- .../src/airflow_breeze/utils/fork_ci_reconcile.py | 6 +++- dev/breeze/tests/test_fork_ci_messages.py | 13 ++++++++ dev/breeze/tests/test_fork_ci_reconcile.py | 27 +++++++++++++++++ 6 files changed, 91 insertions(+), 11 deletions(-) diff --git a/contributing-docs/18_contribution_workflow.rst b/contributing-docs/18_contribution_workflow.rst index 663808a4ed3..78b8a45eac8 100644 --- a/contributing-docs/18_contribution_workflow.rst +++ b/contributing-docs/18_contribution_workflow.rst @@ -156,7 +156,11 @@ Set up your checkout and fork once: gh workflow enable ci-amd.yml -R <you>/airflow GitHub Actions must also be enabled in your fork and allow all actions: ``Tests (AMD)`` uses - actions from other repositories. + actions from other repositories. When your fork's Actions settings block the workflow, its run + ends in "Startup failure" before any job runs, and the fork CI monitor reports + ``Fork CI / Tests (AMD)`` as failed with "could not start". Open the run in your fork for GitHub's + error, which can also be an invalid workflow file, fix the settings under + **Settings > Actions > General** in your fork, and push again. Keep the workflow enabled for as long as you have open pull requests. If it gets disabled, from your fork's Actions tab or by GitHub after 60 days without activity in your fork, the fork CI diff --git a/dev/breeze/doc/ci/08_fork_ci_for_external_contributors.md b/dev/breeze/doc/ci/08_fork_ci_for_external_contributors.md index fdfaf01fb9a..266665d9af5 100644 --- a/dev/breeze/doc/ci/08_fork_ci_for_external_contributors.md +++ b/dev/breeze/doc/ci/08_fork_ci_for_external_contributors.md @@ -549,7 +549,7 @@ stateDiagram-v2 [*] --> running: fork run in progress setup_required --> awaiting_push: author enables the workflow awaiting_push --> running: author pushes - running --> failed: run fails, is cancelled or times out + running --> failed: run fails, is cancelled, times out or cannot start running --> green: run passes, no CI-defining change running --> green_unverified: run passes, CI-defining change failed --> running: author pushes @@ -612,7 +612,7 @@ since the draft-state job runs after the close and GitHub refuses to draft a clo | **setup_required**: workflow state is `disabled_fork`, `disabled_manually` or `disabled_inactivity`, or the fork has no `ci-amd.yml` | `error` (red), link to the fork's Actions page for `ci-amd.yml` | create or update: how to enable, with the exact `gh repo sync <fork> --branch main` and `gh workflow enable ci-amd.yml -R <fork>` lines, and `breeze ci audit`; on transition from any other state but `closed` (the workflow stopped running after it worked): also post a **new** comment sayin [...] | **awaiting_push**: enabled, no run for the head SHA | `pending` (yellow), link to the fork's Actions page | on transition from setup_required: post a **new** comment asking to push again (an edit would not notify) | | **running**: run in progress | `pending` (yellow), link to the run | update state and run link | -| **failed**: conclusion is failure, cancelled or timed out | `failure` (red), link to the run | update with the run link | +| **failed**: conclusion is failure, cancelled, timed out or startup failure | `failure` (red), link to the run; for a startup failure the description says the run could not start | update with the run link; for a startup failure the text says no job ran and points to the fork's Actions settings | | **green**: conclusion success and the pull request does not change CI-defining files | `success` (green), link to the run | update: ready for review, run link; on the author's draft: mark it ready for review when it is | | **green_unverified**: conclusion success, but the pull request changes CI-defining files (see "Trusting a green fork run") | `pending` (yellow), link to the run | update: a maintainer must run project CI; on the author's draft: mark it ready for review, then a maintainer runs project CI | | **closed**: setup_required or awaiting_push for `close_after_days` | unchanged | close with a new comment; reopening restarts the clock | @@ -866,7 +866,16 @@ All comment texts live in `dev/breeze/src/airflow_breeze/utils/fork_ci_messages. templates so wording can be reviewed in one place. Every comment ends with the AI-attribution footer required by `contributing-docs/25_maintainer_pr_triage.md`. The texts must say that CI is free for the contributor and finite for the project, must not characterise the recipient, -and must give the exact command to run. +and must give the exact command to run. They link the contributor documentation +(`contributing-docs/18_contribution_workflow.rst#ci-in-your-fork`) rather than this document, +which that section links for maintainers. + +A fork run that ends in `startup_failure` never ran a job: GitHub rejected the workflow before +running it, most often because the fork's Actions settings do not allow the actions or reusable +workflows it uses, sometimes because the workflow file is invalid. The run has no jobs, so there +are no job statuses either, and GitHub's error is only on the run page. It is handled as `failed`, +but `Fork CI / Tests (AMD)` says "Fork CI run could not start - check your fork's Actions +settings", and the state comment explains what to check instead of asking to fix failures. ### Commit status diff --git a/dev/breeze/src/airflow_breeze/utils/fork_ci_messages.py b/dev/breeze/src/airflow_breeze/utils/fork_ci_messages.py index cf6752b7ffd..314609f52ac 100644 --- a/dev/breeze/src/airflow_breeze/utils/fork_ci_messages.py +++ b/dev/breeze/src/airflow_breeze/utils/fork_ci_messages.py @@ -59,11 +59,11 @@ CI_RUN_STARTED_PROJECT_DESCRIPTION = "Project CI runs in apache/airflow - detail BEHIND_WARNING_COMMITS = 200 MARKER_PREFIX = "<!-- fork-ci-gate: " MARKER_PATTERN = re.compile(r"<!-- fork-ci-gate: (?P<payload>.*?) -->") -DESIGN_URL = ( - "https://github.com/apache/airflow/blob/main/dev/breeze/doc/ci/08_fork_ci_for_external_contributors.md" -) +# Texts on pull requests are for their authors, so they link the contributor documentation; it links +# the design document for maintainers. CONTRIBUTING_URL = ( "https://github.com/apache/airflow/blob/main/contributing-docs/18_contribution_workflow.rst" + "#ci-in-your-fork" ) WHY_AUTOMATED_URL = ( "https://github.com/apache/airflow/blob/main/contributing-docs/25_maintainer_pr_triage.md" @@ -144,7 +144,7 @@ def _setup_instructions(fork: str) -> str: f" *(Or in your browser: open `https://github.com/{fork}/actions` and click 'Enable workflows')*\n\n" "3. Push your branch again. Every push then runs CI in your fork.\n\n" "`breeze ci audit` checks your whole local and fork setup and prints the command that fixes " - f"anything missing. See [the contribution workflow]({CONTRIBUTING_URL})." + f"anything missing. See [CI in your fork]({CONTRIBUTING_URL})." ) @@ -192,6 +192,17 @@ _AUTHOR_DRAFT_TEXTS = { } +# A run that fails to start has no jobs and no log: GitHub rejected the workflow before running it, +# which the generic "failed" text, asking to fix the failures, does not explain. +STARTUP_FAILURE_TEXT = ( + "**Fork CI: could not start.** GitHub could not start the `Tests (AMD)` run for the latest commit " + "in your fork, so no job ran. This usually means that your fork's Actions settings block the " + "workflow: under **Settings > Actions > General** in your fork, GitHub Actions must be enabled and " + "allow all actions and reusable workflows. It can also mean that the workflow file is invalid. The " + "run page in your fork shows GitHub's error. Fix the cause and push again." +) + + def behind_warning(behind: int, *, base_ref: str) -> str: return ( f"**This branch is {behind} commits behind `{base_ref}`.** Fork CI tests the branch as it is, " @@ -201,9 +212,18 @@ def behind_warning(behind: int, *, base_ref: str) -> str: def state_comment( - marker: Marker, *, fork: str, run_url: str | None, base_ref: str = "main", author_draft: bool = False + marker: Marker, + *, + fork: str, + run_url: str | None, + base_ref: str = "main", + author_draft: bool = False, + startup_failure: bool = False, ) -> str: + """:param startup_failure: the fork run of a failed state did not start, see ``STARTUP_FAILURE_TEXT``.""" text = _AUTHOR_DRAFT_TEXTS.get(marker.state) if author_draft else None + if startup_failure: + text = STARTUP_FAILURE_TEXT parts = [render_marker(marker), text or _STATE_TEXTS[marker.state], WHY_FORK_CI] if ( marker.state in ("green", "green_unverified") @@ -215,7 +235,7 @@ def state_comment( parts.append(f"Latest run: {run_url}") if marker.state == "setup_required": parts.append(_setup_instructions(fork)) - parts.append(f"How this works: [fork CI for external contributors]({DESIGN_URL}).") + parts.append(f"How this works: [CI in your fork]({CONTRIBUTING_URL}).") return "\n\n".join(parts) + FOOTER @@ -349,6 +369,8 @@ _STATUS_DESCRIPTIONS = { "awaiting_push": "Fork CI enabled, waiting for a push - see the pull request comment", "running": "Fork CI running - see Details", "failed": "Fork CI failed - see Details", + # Not a state of its own: a failed state whose fork run did not start is handled as failed. + "startup_failure": "Fork CI run could not start - check your fork's Actions settings", "green": "Fork CI passed - see Details", "green_unverified": "Fork CI passed, but CI files changed - a maintainer must run project CI", "gate_bypassed": "Project CI ran for a gated pull request - see Details", @@ -388,6 +410,7 @@ STATUS_STATES = { "awaiting_push": "pending", "running": "pending", "failed": "failure", + "startup_failure": "failure", "green": "success", "green_unverified": "pending", "gate_bypassed": "error", diff --git a/dev/breeze/src/airflow_breeze/utils/fork_ci_reconcile.py b/dev/breeze/src/airflow_breeze/utils/fork_ci_reconcile.py index 60125b3cce8..da56f0c7310 100644 --- a/dev/breeze/src/airflow_breeze/utils/fork_ci_reconcile.py +++ b/dev/breeze/src/airflow_breeze/utils/fork_ci_reconcile.py @@ -839,7 +839,10 @@ def classify( _enter_state(plan, pr, labels, state) target_url = fork.run_url or fork_actions_url(pr.head_repo) - _set_status(plan, pr, state.value, target_url, force=refresh_status) + startup_failure = state == ForkState.FAILED and fork.suite_conclusion == "STARTUP_FAILURE" + _set_status( + plan, pr, "startup_failure" if startup_failure else state.value, target_url, force=refresh_status + ) _set_ci_passed(plan, pr, passed=state == ForkState.GREEN, target_url=target_url) _set_ci_run_started(plan, pr, fork) green = state in (ForkState.GREEN, ForkState.GREEN_UNVERIFIED) @@ -859,6 +862,7 @@ def classify( run_url=fork.run_url, base_ref=pr.base_ref, author_draft=_is_author_draft(pr), + startup_failure=startup_failure, ), ) return plan diff --git a/dev/breeze/tests/test_fork_ci_messages.py b/dev/breeze/tests/test_fork_ci_messages.py index 7ef307733fd..3b5b327593b 100644 --- a/dev/breeze/tests/test_fork_ci_messages.py +++ b/dev/breeze/tests/test_fork_ci_messages.py @@ -30,6 +30,7 @@ from airflow_breeze.utils.fork_ci_messages import ( CI_MODIFICATION_MARKER, CI_PASSED_DESCRIPTION, CI_PASSED_REVOKED_DESCRIPTION, + CONTRIBUTING_URL, FOOTER, GATED_NOTE_SENTENCE, JOB_NAME_MAX_LENGTH, @@ -108,6 +109,18 @@ def test_state_comment_asks_the_author_to_mark_a_green_draft_ready(state, author assert ("ask a maintainer to mark it ready" in text) is asks_to_mark_ready [email protected]("startup_failure", [False, True]) +def test_state_comment_links_the_contributor_documentation(startup_failure): + text = state_comment( + Marker("failed", "a", MARKER.since), fork="u/airflow", run_url=None, startup_failure=startup_failure + ) + + assert f"How this works: [CI in your fork]({CONTRIBUTING_URL})." in text + assert CONTRIBUTING_URL.endswith("18_contribution_workflow.rst#ci-in-your-fork") + assert "08_fork_ci_for_external_contributors" not in text + assert text.endswith(FOOTER) + + def test_parse_marker_absent(): assert parse_marker("just a comment") is None diff --git a/dev/breeze/tests/test_fork_ci_reconcile.py b/dev/breeze/tests/test_fork_ci_reconcile.py index 9ecba69d3c0..b9714bb70c0 100644 --- a/dev/breeze/tests/test_fork_ci_reconcile.py +++ b/dev/breeze/tests/test_fork_ci_reconcile.py @@ -241,6 +241,33 @@ def test_setup_required_comment_gives_the_command(): assert "gh workflow enable ci-amd.yml -R someone/airflow" in plan.marker_comment [email protected]( + ("conclusion", "expected_description", "explains_settings"), + [ + pytest.param( + "STARTUP_FAILURE", + "Fork CI run could not start - check your fork's Actions settings", + True, + id="startup-failure", + ), + pytest.param("FAILURE", "Fork CI failed - see Details", False, id="failure"), + ], +) +def test_a_run_that_could_not_start_points_to_the_fork_settings( + conclusion, expected_description, explains_settings +): + fork = ForkObservation(suite_status="COMPLETED", suite_conclusion=conclusion, run_url=RUN_URL) + + plan, _, _ = _classify(_pr(is_draft=False), fork) + + assert plan.state == ForkState.FAILED + assert plan.draft is None + assert plan.status == ("failure", RUN_URL, expected_description) + assert ("**Fork CI: could not start.**" in plan.marker_comment) is explains_settings + assert ("Settings > Actions > General" in plan.marker_comment) is explains_settings + assert '"state": "failed"' in plan.marker_comment + + @pytest.mark.parametrize( ("fork", "draft"), [
