Skip to content

docs: explain the Enable CI on your fork check in the contributor guide - #7352

Merged
andygrove merged 4 commits into
apache:mainfrom
andygrove:docs/fork-ci-enable-check
Nov 17, 2026
Merged

andygrove merged 4 commits into
apache:mainfrom
andygrove:docs/fork-ci-enable-check

Conversation

@andygrove

Copy link
Copy Markdown
Member

Which issue does this PR close?

No issue filed. Follow-up to #7311.

Rationale for this change

Since #7311, the PR tier for a fork pull request into main runs on the contributor's fork, and the CI (fork) check mirrors that run onto the pull request. When the fork has Actions disabled, the check reports Enable CI on your fork, which GitHub shows as a failure. Most forks have Actions disabled, because GitHub disables workflows on a new fork, so this check is now showing up on fork pull requests such as #7343. The guide covered the setup steps, but only one sentence covered this failure, and it did not say what the red check means for merging, what to run, or why a pull request opened before the change gets it too.

What changes are included in this PR?

  • ci.md: a new "When the fork check finds no run" subsection under "Pull requests from forks". It explains the two messages (Enable CI on your fork and No fork CI run for this commit), says the check does not block merging but means the PR tier has not run, and gives the commands to fix it. It also notes that enabling Actions needs a new push, and covers pull requests opened before the change. The old one-sentence explanation now links to the subsection. The check's own details link still lands on "Pull requests from forks", directly above the new subsection.
  • development.md: the fork paragraph under "Submitting a Pull Request" now names the failing check and links to the subsection.

How are these changes tested?

Documentation only. Checked with prettier. The described behavior matches fork_ci_status.yml on main.

@github-actions github-actions Bot added the documentation Improvements or additions to documentation label Oct 30, 2026

@sunchao sunchao left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The setup commands point contributors to the right workflow. I found two places where the text overstates what the fork check can establish. The inline comments include examples from this rollout.

Comment thread docs/source/contributor-guide/ci.md Outdated
- **Enable CI on your fork.** Your fork has no enabled `Comet CI (fork run)` workflow. Usually
GitHub Actions was never enabled on the fork, or no branch that includes the fork workflows has
been pushed to it. GitHub shows this check as failed because it asks you to act. It does not block
merging, but the PR tier has not run on this commit anywhere, so a reviewer has no CI result to

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

A missing fork run establishes only that the mirror found no run on the fork for this SHA. On #7316, commit cd5dda1c has both “Enable CI on your fork” and a successful upstream PR-tier Rust job. Could we say that earlier upstream results may still exist? The rollout paragraph below also predicts a failed check for older PRs, but #7326 received the neutral “No fork CI run for this commit” outcome. #7316 fork check · #7316 upstream test · #7326 neutral check

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Good point. The first bullet no longer says that the PR tier has not run anywhere. It says the check only means that no run of the fork was found for this commit, and that a pull request opened before the PR tier moved to forks can still have upstream results. The rollout paragraph now describes both outcomes: the failed Enable CI on your fork check when the fork has no enabled workflow, and the neutral No fork CI run for this commit one when it has, which is what #7326 got (5070f61).

rather than the project's. Enable GitHub Actions on your fork and keep its `main` in sync before you
push; see [Pull requests from forks](ci.md#pull-requests-from-forks).
push; see [Pull requests from forks](ci.md#pull-requests-from-forks). Until you do, the pull
request shows a failed `CI (fork)` check that says **Enable CI on your fork**, and the PR tier

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Could we qualify this as a fork PR targeting main? The mirror filters on pr.base.ref === 'main'. Fork PRs targeting a release branch run their PR tier upstream, so contributors to those branches won’t see this check. #7351 is a current example. Mirror filter · #7351 upstream run

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Qualified. The paragraph is about a pull request from a fork that targets main, and it says that one that targets a release branch keeps the PR tier on the project's runners and has no CI (fork) check. ci.md already says that a release branch keeps the PR tier here.

Comment thread docs/source/contributor-guide/ci.md Outdated
Comment on lines +179 to +182
merging. The check says only that no run of your fork was found for this commit. A pull request
opened before the PR tier moved to forks can still have results of the PR tier from here, as
[below](#when-the-fork-check-finds-no-run) says, and otherwise a reviewer has no CI result to go
on.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for reworking this bullet. Two small things in the new sentence. "Otherwise a reviewer has no CI result to go on" goes a bit further than the check can show. The preflight checks, Required Checks, and any run-* suite still run here, as the top of this section says, and this PR's own Preflight run shows that. Could it say that the PR tier has not run for this commit instead? Also, the "below" link goes to #when-the-fork-check-finds-no-run, which is this subsection's own heading, so it jumps up rather than down to the rollout paragraph. Maybe something like: "...can still have results of the PR tier from here, as the last paragraph of this section says. Otherwise the PR tier has not run for this commit, and only the preflight checks and any run-* suites have run here."

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Changed as suggested. The first bullet now says the PR tier has not run for this commit and that only the preflight checks and any run-* suites have run here, and the link now points to the last paragraph of the section (f8aa438).

Comment thread docs/source/contributor-guide/ci.md Outdated
Comment on lines +183 to +186
- **No fork CI run for this commit.** The workflow exists but has no run for this commit. Either
the run has not appeared yet, or the commit was pushed before Actions was enabled.

Either way, the fix is the three steps above, followed by a new push:

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The old sentence listed "the branch does not include the fork workflows" as a cause, and I think it belongs back in this bullet. Say someone enables Actions and syncs their fork's main, but their PR branch predates #7311. Then getWorkflow finds an active ci_fork.yml, the branch push starts nothing, and the mirror reports the neutral No fork CI run for this commit. That is also the case the rollout paragraph describes. As written, someone in that state could read this as "wait for the run to appear." Could we write "Either the run has not appeared yet, your branch does not include the fork workflows, or the commit was pushed before Actions was enabled"? Then "Either way, the fix is..." doesn't quite fit the "not appeared yet" case. Maybe "If your fork's Actions tab has no run for this commit, the fix is..."?

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Restored. The second bullet now lists the run not having appeared yet, the branch not including the fork workflows, and the commit having been pushed before Actions was enabled. The sentence after it now starts "If your fork's Actions tab has no run for this commit" (f8aa438).

Comment thread docs/source/contributor-guide/ci.md Outdated
Comment on lines +192 to +193
git merge upstream/main # 3. bring the fork workflows into your branch (or rebase)
git push # starts a Comet CI (fork run) in your fork

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Step 2 above asks readers to rebase onto main, and this line offers "(or rebase)". After a rebase, the plain git push on the next line is rejected as a non-fast-forward. Could the comment say to push with git push --force-with-lease after a rebase, as development.md asks?

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Good catch. The comment on the push line now says to use --force-with-lease after a rebase (f8aa438).

@andygrove
andygrove enabled auto-merge November 16, 2026 21:50
@andygrove

Copy link
Copy Markdown
Member Author

Thanks for the review @kazuyukitanimura. I addressed all three comments in f8aa438. I plan to merge once CI is green.

@andygrove
andygrove added this pull request to the merge queue Nov 16, 2026
Merged via the queue into apache:main with commit 4b5a392 Nov 17, 2026
24 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

documentation Improvements or additions to documentation

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants