Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
20 changes: 12 additions & 8 deletions contributing-docs/05_pull_requests.rst
Original file line number Diff line number Diff line change
Expand Up @@ -252,10 +252,12 @@ and approves them automatically when all of these hold:

* The PR targets ``main``. PRs to release branches, such as ``v3-4-test``, always wait for a
maintainer.
* The PR does not change files that define CI: anything under ``.github/``, ``dev/breeze/``,
``scripts/ci/``, ``scripts/docker/`` or ``scripts/in_container/``, a top-level ``Dockerfile*``,
or a ``.pre-commit-config.yaml`` in any directory. Those files define the CI workflows, what
their jobs run and the runners they use.
* The PR does not change files that decide which CI jobs run and on which runners: anything under
``.github/``, ``dev/breeze/src/`` or ``scripts/ci/prek/``, or ``dev/breeze/pyproject.toml``,
``dev/breeze/uv.lock`` or ``scripts/ci/install_breeze.sh``. Changes to the other files CI uses
(the rest of ``dev/breeze/`` and ``scripts/ci/``, ``scripts/docker/``, ``scripts/in_container/``,
``Dockerfile*``, ``.pre-commit-config.yaml``) are not held, but a one-time comment on the PR
points them out to the reviewer.
* The change does not need the full set of tests, does not change dependencies (``pyproject.toml``,
lock files, ``package.json``, ``go.mod``, Gradle build files) and does not add a new provider.
* The CI jobs your change selects are estimated to take at most 310 job-minutes, about a quarter of
Expand All @@ -271,10 +273,12 @@ and approves them automatically when all of these hold:
If your PR's CI runs in your fork (it carries the ``fork ci required`` label), the CI run in
``apache/airflow`` only checks that, so none of the rules above apply. The ``CI run started`` check
waits until the fork CI monitor sees your fork's run, usually within 15 minutes, and then links it. Its runs are approved
automatically unless the PR changes files that define CI: anything under ``.github/``,
``dev/breeze/``, ``scripts/ci/``, ``scripts/docker/`` or ``scripts/in_container/``, a top-level
``Dockerfile*``, or a ``.pre-commit-config.yaml`` in any directory. Then the runs wait for a maintainer and a comment on the PR explains
why. CI in your fork runs either way.
automatically unless the PR changes files that decide which CI jobs run and on which runners:
anything under ``.github/``, ``dev/breeze/src/`` or ``scripts/ci/prek/``, or
``dev/breeze/pyproject.toml``, ``dev/breeze/uv.lock`` or ``scripts/ci/install_breeze.sh``. Then
the runs wait for a maintainer and a comment on the PR explains why. Changes to the other files
CI uses are not held, but a one-time comment points them out to the reviewer. CI in your fork
runs either way.

The runs of PRs opened from the repositories of trusted stakeholders (``astronomer/airflow``,
``aws-mwaa/upstream-to-airflow`` and ``VladaZakharova/airflow``) are always approved, so none of
Expand Down
4 changes: 2 additions & 2 deletions contributing-docs/18_contribution_workflow.rst
Original file line number Diff line number Diff line change
Expand Up @@ -173,8 +173,8 @@ request explains the current state. Once the run is green, a pull request the mo
marked ready for review and labelled ``ready for maintainer review``; a pull request you drafted
yourself stays a draft, and gets the label, once you mark it ready. A pull request whose fork CI
does not run for 7 days is closed with an explanation; you can reopen it after setting up fork CI. If your pull request changes
files that define what CI runs, such as ``.github/``, ``dev/breeze/`` or ``scripts/ci/``, a green
fork run is not enough: a maintainer reviews the change and runs project CI for it.
files that decide which CI jobs run and where, such as ``.github/``, the breeze sources or
``scripts/ci/prek/``, a green fork run is not enough: a maintainer reviews the change and runs project CI for it.

**Joining the pilot.** Open a pull request that adds your GitHub login to the ``[pilot]`` table in
``.github/fork-ci-gate.toml``, with a join instant after the expected merge, for example the next day
Expand Down
16 changes: 10 additions & 6 deletions contributing-docs/25_maintainer_pr_triage.md
Original file line number Diff line number Diff line change
Expand Up @@ -260,7 +260,9 @@ for them, and the triage skill must treat those pull requests as out of scope fo
removes it when a new push starts a new run.
- **`needs project ci`.** The reconciler adds it when the fork run is green but the pull request
changes CI-defining files, and removes it once the state is anything else. These pull requests
stay in draft and wait for a maintainer to review the CI change and add `use project ci`.
are not drafted and get no `ready for maintainer review` label. Their `Fork CI / Tests (AMD)`
status stays pending without `CI passed`, and they keep `needs project ci` until a maintainer
reviews the CI change and adds `use project ci`.
- **Closing for changing the gate.** The reconciler closes a pull request that changes the fork
CI gate (its code, configuration other than the author's own `[pilot]` entry, the `gate` job
of `ci-amd.yml` or the monitor), and reports it on Slack. Add `use project ci` to accept such
Expand All @@ -275,11 +277,13 @@ releases it on its next run; removing `fork ci required` by hand is not enough,
labels a gated pull request again. Adding the label does not start project CI by itself, and the
reconciler deletes the gated `Tests (AMD)` runs, so there is usually nothing to re-run: close and
reopen the pull request (`gh pr close <n> -R apache/airflow && gh pr reopen <n> -R apache/airflow`),
or ask the author to push. Pull requests that change CI-defining files stay in draft even
when the fork run is green and are labelled `needs project ci`, for a maintainer to review and run
project CI with `use project ci`. When the fork run is green and trusted, the reconciler also posts
the `CI passed` status the merge ruleset requires, so these pull requests can be merged or
auto-merged without project CI. See
or ask the author to push. Pull requests that change CI-defining files are not drafted
and get no `ready for maintainer review` label even when the fork run is green. Their
`Fork CI / Tests (AMD)` status stays pending without `CI passed`, and they are labelled
`needs project ci` until a maintainer reviews the CI change and adds `use project ci`. For
every other pull request, when the fork run is green and trusted, the reconciler also posts the
`CI passed` status the merge ruleset requires, so it can be merged or auto-merged without project
CI. See
[Fork CI for external contributors](../dev/breeze/doc/ci/08_fork_ci_for_external_contributors.md).

## For contributors
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -102,8 +102,9 @@ record captures the decisions that shape it and the alternatives rejected.
``.github/workflows/``, and legitimate workflow edits that keep the gate intact, are never
closed. A pull request that is gated again after legitimate project CI runs and also edits
workflows can still be closed while those runs are in the tampering window. A green fork run is trusted only when the pull request does not
change what fork CI runs (``.github/``, ``dev/breeze/``, ``scripts/ci/`` and the like);
otherwise it stays a draft until a maintainer runs project CI. A trusted green fork run also
change the ``build-info`` outputs that decide which jobs run and where (``.github/``, the
breeze sources, the breeze installation and ``scripts/ci/prek/``); otherwise it is labelled ``needs project ci``
and cannot merge until a maintainer runs project CI. A trusted green fork run also
gets a ``CI passed`` commit status, the check the merge ruleset requires, because a gated
pull request never runs project CI to report it; it is only ever posted as success, and
overwritten when the head commit is no longer green. Commit statuses were chosen over check
Expand Down
10 changes: 6 additions & 4 deletions dev/breeze/doc/ci/05_workflows.md
Original file line number Diff line number Diff line change
Expand Up @@ -107,10 +107,12 @@ them, for the contributors the repository's approval setting covers. The

- the PR targets `main`; PRs to release branches (`v3-4-test`, `airflow-ctl/v0-1-test`, ...) run those
branches' own workflows and always wait for a maintainer
- the PR changes no file the fork CI reconciler counts as CI-defining (`.github/`, `dev/breeze/`,
`scripts/ci/`, `scripts/docker/`, `scripts/in_container/`, a top-level `Dockerfile*`, a
`.pre-commit-config.yaml` in any directory),
which define the workflows, what their jobs run and the runners they use
- the PR changes no file the fork CI reconciler counts as CI-defining (`.github/`, `dev/breeze/src/`,
`dev/breeze/pyproject.toml`, `dev/breeze/uv.lock`, `scripts/ci/install_breeze.sh` and
`scripts/ci/prek/`), which decide which jobs run and on which runners. Changes to the other files
CI uses (the rest of `dev/breeze/` and `scripts/ci/`, `scripts/docker/`, `scripts/in_container/`,
`Dockerfile*`, `.pre-commit-config.yaml`) are not held, but get a one-time
`<!-- workflow-approval: ci-modification -->` note comment on the PR for the reviewer
- the PR changes no dependency manifest or lock file (`pyproject.toml`, `uv.lock`, `package.json`,
`pnpm-lock.yaml`, `go.mod`, Gradle build files, ...) and adds no new provider (selective checks
run from `main`'s tree and do not know it)
Expand Down
42 changes: 29 additions & 13 deletions dev/breeze/doc/ci/08_fork_ci_for_external_contributors.md
Original file line number Diff line number Diff line change
Expand Up @@ -380,9 +380,9 @@ created after it are approved this way, while earlier ones, whose gate ran proje
maintainer. One rule applies instead:

- The waiting runs of the head commit are approved when the pull request's merge commit changes no
file that the reconciler counts as CI-defining: `.github/`, `dev/breeze/`, `scripts/ci/`,
`scripts/docker/`, `scripts/in_container/`, `Dockerfile*` and `.pre-commit-config.yaml` (see
"Trusting a green fork run"). The approved `ci-amd.yml` run executes only the gate, and the other
file that the reconciler counts as CI-defining: `.github/`, `dev/breeze/src/`,
`dev/breeze/pyproject.toml`, `dev/breeze/uv.lock`, `scripts/ci/install_breeze.sh` and
`scripts/ci/prek/` (see "Trusting a green fork run"). The approved `ci-amd.yml` run executes only the gate, and the other
`pull_request` workflows (CodeQL for the changed languages, the newsfragment check, dependency
review) run on GitHub-hosted runners.
- Otherwise the runs wait for a maintainer, its head commit gets a pending `Workflow approval`
Expand All @@ -393,6 +393,12 @@ maintainer. One rule applies instead:
workflow that does run, so such a run must not start without a review. The pull request does
not get the `need workflow approval` label, and loses it if it has it. Approving its runs does
not start project CI. A maintainer adds `use project ci` for that.
- A pull request that changes other files CI uses (the rest of `dev/breeze/` and `scripts/ci/`,
`scripts/docker/`, `scripts/in_container/`, `Dockerfile*` or `.pre-commit-config.yaml`) is not
held for them, but gets one comment listing them, so the reviewer checks the CI change with the
rest of the diff. It starts with the marker `<!-- workflow-approval: ci-modification -->` and is
posted once per pull request, for pull requests that run project CI as well. Like the rest of
this workflow, it only reaches pull requests whose runs waited for approval.

A run started before `use fork ci` or `use project ci` was last added or removed is approved too,
so a committer can add `use fork ci` after the PR's first runs were created and before they are
Expand Down Expand Up @@ -532,7 +538,7 @@ pull requests without a fork run for their head commit, not by the total.
| **running**: run in progress | unchanged (a rebase of an approved pull request does not draft it; a failed run does) | remove | `pending` (yellow), link to the run | update state and run link |
| **failed**: conclusion is failure, cancelled or timed out | draft | remove | `failure` (red), link to the run | update with the run link |
| **green**: conclusion success and the pull request does not change CI-defining files | undraft\* | add | `success` (green), link to the run | update: ready for review, run link |
| **green_unverified**: conclusion success, but the pull request changes CI-defining files (see "Trusting a green fork run") | draft | remove | `pending` (yellow), link to the run | update: a maintainer must run project CI; labelled `needs project ci` |
| **green_unverified**: conclusion success, but the pull request changes CI-defining files (see "Trusting a green fork run") | undraft\* | remove | `pending` (yellow), link to the run | update: a maintainer must run project CI; labelled `needs project ci` |
| setup_required or awaiting_push for `close_after_days` | unchanged | unchanged | unchanged | close with a new comment; reopening restarts the clock |
| **ungated**: the base branch has no gate, for example after retargeting to an older release branch | undraft\* | unchanged | `success` (green), link to the pull request's checks | update: project CI is in use; `fork ci required` is removed |
| **gate_modified**: the pull request changes the fork CI gate (see "Gate protection") | draft | remove | `error` (red), link to the pull request's changed files | post a **new** comment explaining why, then close; checked after gate tampering, before the fork state |
Expand Down Expand Up @@ -582,17 +588,26 @@ Rules that sit under the table:

### Trusting a green fork run

The fork run executes the workflow files, the breeze sources and the CI scripts of the pushed
commit. A pull request that changes them decides what its own fork CI checks, and could make it
pass trivially. When a new head commit turns green, the reconciler lists the pull request's
The fork run executes the workflow files and the breeze sources of the pushed commit, and the
`build-info` job decides from them which jobs run and on which runners. A pull request that
changes them decides what its own fork CI checks, and could make it pass trivially. CI-defining
files are only those that change the `build-info` outputs: the workflows and actions, the breeze
sources whose selective checks compute the outputs, the files that install breeze, and
`scripts/ci/prek/`. Selective checks runs `scripts/ci/prek/update_providers_dependencies.py` to
generate the gitignored `generated/provider_dependencies.json`, and the script runs with its
directory first on `sys.path`, so any module added there would run as well. Other CI
scripts, Dockerfiles and prek configuration change only what a selected job does, so they are
reviewed with the rest of the diff and do not hold the pull request back. When a new head commit turns green, the reconciler lists the pull request's
changed files once (`GET /repos/apache/airflow/pulls/<n>/files`) and then reads the head commit
again: the files endpoint lists the current head, so when the head moved meanwhile nothing is
decided or recorded for the old commit, and the next run decides for the new one. If any file is under `.github/`,
`dev/breeze/`, `scripts/ci/`, `scripts/docker/` or `scripts/in_container/`, is a
`Dockerfile*` or a `.pre-commit-config.yaml`, or the list reaches GitHub's 3000-file cap so the
rest cannot be seen, the state is `green_unverified` instead of `green`. The pull request stays
a draft, the status is pending, and it is labelled `needs project ci` so maintainers can list
these pull requests, review the change and add `use project ci`. It is not posted to Slack:
`dev/breeze/src/` or `scripts/ci/prek/`, is `dev/breeze/pyproject.toml`, `dev/breeze/uv.lock` or
`scripts/ci/install_breeze.sh`, or the list reaches GitHub's 3000-file cap so the rest cannot be
seen, the state is `green_unverified` instead of `green`. The pull request is not drafted (a
draft the reconciler made earlier is undone, as for `green`), but it gets no review label, the
status is pending, and it is labelled `needs project ci` so maintainers can list these pull
requests, review the change and add `use project ci`. Without `CI passed` it cannot be merged
until then. It is not posted to Slack:
the label already lists these pull requests, and a post for every new green commit would bury
the CI breakages that channel is for.
The reconciler removes `needs project ci` as soon as the state is anything else. A renamed file
Expand Down Expand Up @@ -1243,7 +1258,8 @@ as a failed check rather than a crash.
the conflicting-labels alert, the close clock reset (including a reopen after an inactivity
close), a fork with a name other than `airflow`, marker round-trips, status
desired-vs-current comparison, the unknown-failure collection, green trust (a change to
CI-defining files keeps the pull request a draft, decided once per commit) and the gate
CI-defining files keeps the status pending without drafting the pull request, decided once
per commit) and the gate
tampering check: a tampered run on an earlier commit is caught after a clean push, each
signal alone does not close, short runs and gate-only jobs do not count, an in-progress
non-gate job, a removed, duplicated or long-running gate job and an injected workflow with a
Expand Down
35 changes: 30 additions & 5 deletions dev/breeze/src/airflow_breeze/utils/fork_ci_messages.py
Original file line number Diff line number Diff line change
Expand Up @@ -155,9 +155,10 @@ def _setup_instructions(fork: str) -> str:
"green": "**Fork CI: green.** CI for the latest commit passed in your fork. The pull request is "
"ready for maintainer review.",
"green_unverified": "**Fork CI: green, needs a maintainer.** CI for the latest commit passed in your "
"fork, but this pull request changes files that define what CI runs (such as `.github/`, "
"`dev/breeze/` or `scripts/ci/`), and the fork run used those changed files. A maintainer will "
"review the change and run project CI for it; the pull request stays a draft until then.",
"fork, but this pull request changes files that decide which CI jobs run and where (`.github/`, "
"the breeze sources, the breeze installation or `scripts/ci/prek/`), and the fork run used those "
"changed files. A maintainer will review the change and run project CI for it before it can be "
"merged.",
"closed": "**Fork CI: closed after inactivity.** CI did not run in your fork in time; see the "
"comment below for how to continue.",
"gate_bypassed": "**Fork CI: closed.** Project CI ran for this pull request although its CI runs in "
Expand Down Expand Up @@ -275,22 +276,46 @@ def _sanitize_path(path: str) -> str:
return "".join(char if char.isprintable() and char != "`" else "?" for char in path)


def ci_change_approval_comment(*, ci_files: list[str]) -> str:
def build_ci_file_list(ci_files: list[str]) -> str:
listed = [f"- `{_sanitize_path(path)}`" for path in ci_files[:MAX_LISTED_CI_FILES]]
if len(ci_files) > MAX_LISTED_CI_FILES:
listed.append(f"- and {len(ci_files) - MAX_LISTED_CI_FILES} more")
return "\n".join(listed)


def ci_change_approval_comment(*, ci_files: list[str]) -> str:
return (
f"{CI_CHANGE_MARKER}\n\n"
"**Your CI change needs a maintainer.** CI for this pull request runs in your fork, and the "
"workflow runs it starts in apache/airflow are approved automatically while they only run the "
"fork CI gate. This pull request changes files that define what CI runs:\n\n"
+ "\n".join(listed)
+ build_ci_file_list(ci_files)
+ "\n\nSuch a change can make project CI run on the project's runners, so its workflow runs in "
"apache/airflow wait for a maintainer to review the change and approve them. CI in your fork "
"is not affected, and its result stays visible on this pull request. " + WHY_FORK_CI + FOOTER
)


CI_MODIFICATION_MARKER = "<!-- workflow-approval: ci-modification -->"


GATED_NOTE_SENTENCE = (
" CI for this pull request runs in the author's fork, so any green result and `CI passed` status will "
"come from a run that executed these changed files."
)


def ci_modification_note_comment(*, ci_files: list[str], gated: bool) -> str:
return (
f"{CI_MODIFICATION_MARKER}\n\n"
"**This pull request changes CI files.** It changes files that CI uses:\n\n"
+ build_ci_file_list(ci_files)
+ "\n\nThey do not decide which CI jobs run or on which runners, so its workflow runs are not "
"held for this. A maintainer reviewing the pull request will check the CI change together with "
"the rest of it." + (GATED_NOTE_SENTENCE if gated else "") + FOOTER
)


_STATUS_DESCRIPTIONS = {
"setup_required": "Fork CI not set up - see the pull request comment",
"awaiting_push": "Fork CI enabled, waiting for a push - see the pull request comment",
Expand Down
Loading