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"),
     [

Reply via email to