Skip to content

Free fork of NotProton: Windows Steam games in Mac Steam, on CodeWeavers' Wine and Apple's Game Porting Toolkit

ci(app): add an always-running app gate, build beta pushes, reuse only full CI runs

Raystorms37776e2d811f
diff --git a/.github/docs-only-paths b/.github/docs-only-paths
new file mode 100644
index 0000000..0dfb7a7
--- /dev/null
+++ b/.github/docs-only-paths
@@ -0,0 +1,6 @@
+# A change that touches only these paths is docs-only: the app workflow skips its build
+# and check jobs and its gate still passes. Anything else runs everything.
+# One shell glob per line, matched against the repo-relative path; * also matches /.
+# scripts/build-local.sh reads this file too, when it decides which CI runs it can reuse.
+*.md
+docs/*
diff --git a/.github/workflows/app.yml b/.github/workflows/app.yml
index 285a56f..2ec0c58 100644
--- a/.github/workflows/app.yml
+++ b/.github/workflows/app.yml
@@ -1,21 +1,24 @@
name: app
-# Markdown and docs/ changes build nothing. scripts/build-local.sh skips the same paths
-# when it reuses a passing run for a release.
+# Starts on every PR and every push to main and beta, so the "app gate" job below always
+# reports: it is the check a branch rule can require. The scope job decides whether the
+# change is docs-only (.github/docs-only-paths); if so the build and checks jobs are
+# skipped and the gate passes. scripts/build-local.sh reuses a run for a release only when
+# those two jobs ran and succeeded (scripts/ci-run-passed.sh), so keep their names.
on:
push:
- branches: [main]
- paths: ["**", "!**/*.md", "!docs/**"]
+ branches: [main, beta]
pull_request:
- paths: ["**", "!**/*.md", "!docs/**"]
workflow_dispatch:
permissions:
contents: read
-# A newer push to the same PR replaces the run; pushes to main all finish.
+# A newer push to the same PR replaces the run. Every push to main or beta (and every manual
+# run) has a group of its own, so none is cancelled, and none is dropped from the queue
+# the way a pending run is when a third arrives in a shared group.
concurrency:
- group: app-${{ github.ref }}
+ group: app-${{ github.event_name == 'pull_request' && github.ref || github.run_id }}
cancel-in-progress: ${{ github.event_name == 'pull_request' }}
env:
@@ -26,8 +29,28 @@ env:
HOMEBREW_NO_INSTALLED_DEPENDENTS_CHECK: "1"
jobs:
+ scope:
+ name: change scope
+ runs-on: ubuntu-latest
+ timeout-minutes: 5
+ outputs:
+ docs_only: ${{ steps.scope.outputs.docs_only }}
+ steps:
+ - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4.4.0
+ with:
+ fetch-depth: 2
+
+ - name: Decide whether the change is docs-only
+ id: scope
+ env:
+ EVENT: ${{ github.event_name }}
+ BEFORE: ${{ github.event.before }}
+ run: sh scripts/ci-scope.sh | tee -a "$GITHUB_OUTPUT"
+
build:
name: full app build
+ needs: scope
+ if: needs.scope.outputs.docs_only != 'true'
runs-on: xcode-27
timeout-minutes: 30
steps:
@@ -159,6 +182,8 @@ jobs:
checks:
name: source checks
+ needs: scope
+ if: needs.scope.outputs.docs_only != 'true'
runs-on: xcode-27
timeout-minutes: 20
steps:
@@ -170,3 +195,23 @@ jobs:
# Each check builds what it needs; none reads the app build.
- name: Run the checks
run: make ci-checks-source
+
+ # The one check a branch rule requires. always(): a skipped required check counts as
+ # passing, so a gate skipped because build or checks failed or were cancelled would let
+ # the change in. scripts/ci-gate.sh says what is green.
+ gate:
+ name: app gate
+ needs: [scope, build, checks]
+ if: always()
+ runs-on: ubuntu-latest
+ timeout-minutes: 5
+ steps:
+ - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4.4.0
+
+ - name: Check the verdict
+ env:
+ SCOPE_RESULT: ${{ needs.scope.result }}
+ DOCS_ONLY: ${{ needs.scope.outputs.docs_only }}
+ BUILD_RESULT: ${{ needs.build.result }}
+ CHECKS_RESULT: ${{ needs.checks.result }}
+ run: sh scripts/ci-gate.sh
diff --git a/.github/workflows/lint.yml b/.github/workflows/lint.yml
index b5e8772..f52881d 100644
--- a/.github/workflows/lint.yml
+++ b/.github/workflows/lint.yml
@@ -2,7 +2,7 @@ name: lint
on:
push:
- branches: [main]
+ branches: [main, beta]
pull_request:
workflow_dispatch:
diff --git a/AGENTS.md b/AGENTS.md
index a2f84b3..c0f55c6 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -34,8 +34,9 @@ More docs: [docs/WINECX.md](docs/WINECX.md) (engine, patch build recipes and pin
## Build and check
A full build needs an Apple Silicon Mac with Xcode 27. Prerequisites, caches and timings
-are in [docs/BUILD-LOCAL.md](docs/BUILD-LOCAL.md). The workflows run only `make scriptcheck`
-and `make runcheck` (shellcheck 0.11.0) on Linux; everything else runs on macOS.
+are in [docs/BUILD-LOCAL.md](docs/BUILD-LOCAL.md). The lint workflow runs only `make scriptcheck`
+and `make runcheck` (shellcheck 0.11.0) on Linux. The `app` workflow decides on Linux whether a change is
+docs-only (`.github/docs-only-paths`) and ends in the `app gate` job; everything else runs on macOS.
```sh
scripts/build-local.sh # full build in CI order; --checks also runs checks and Swift tests
@@ -60,7 +61,7 @@ The checks the workflows run (`make -s <target>`):
- **C and shell suites:** `sigcheck`, `callscheck`, `webpatch-fixtures`, `peicon-fixtures`,
`panel-behavior`, `spawn-env`, `activatecheck`, `compatcheck`, `compatsvc-check`,
`shortcutcheck`, `launch-shell`, `envcheck`, `buildcheck`, `settingscheck`, `routecheck`,
- `bridgecheck`, `gamedrivecheck`, `launchercheck`, `seedcheck`, `gamefixescheck`
+ `bridgecheck`, `gamedrivecheck`, `launchercheck`, `seedcheck`, `gamefixescheck`, `cicheck`
- **Hardware-free device checks:** `game-host-check`, `dualsense-check`, `steam-rumble-check`
`make tests-list` prints the test paths. A check whose tool or input is missing prints
diff --git a/Makefile b/Makefile
index d3fb076..0c20877 100644
--- a/Makefile
+++ b/Makefile
@@ -74,7 +74,7 @@ DEPS := $(OBJS:.o=.d)
overlay-shim-bench iconmaker icon \
appinfo helpers-install ntdll-resolve bridge runcheck compatcheck \
compatsvc-check shortcutcheck scriptcheck envcheck buildcheck settingscheck routecheck bridgecheck gamedrivecheck \
- gamefixescheck launchercheck padcheck launch-shell activatecheck FORCE
+ gamefixescheck launchercheck padcheck launch-shell activatecheck cicheck FORCE
APP_PAYLOAD := app/Sources/BridgeplayApp/Resources/payload
@@ -87,7 +87,7 @@ dylib: $(TARGET)
$(APP_PAYLOAD):
@mkdir -p $(APP_PAYLOAD)
-TEST_PATHS := dylib/tests overlay-shim/tests app/Tests
+TEST_PATHS := dylib/tests overlay-shim/tests app/Tests scripts/tests
tests-list:
@for p in $(TEST_PATHS); do echo $$p; done
@@ -101,6 +101,10 @@ runcheck:
shellcheck dylib/feats/compat_run.sh && sh -n dylib/feats/compat_run.sh && \
echo "==> runcheck: the run script lints and parses clean"
+cicheck:
+ @if [ ! -f scripts/tests/cicheck.sh ]; then $(call SKIP,cicheck,scripts/tests/cicheck.sh); exit 0; fi; \
+ sh scripts/tests/cicheck.sh
+
.PHONY: seedcheck
seedcheck:
@if [ ! -f dylib/tests/seedcheck.sh ]; then $(call SKIP,seedcheck,dylib/tests/seedcheck.sh); exit 0; fi; \
@@ -888,7 +892,7 @@ CI_CHECKS := mincheck l10ncheck \
sigcheck callscheck webpatch-fixtures peicon-fixtures panel-behavior spawn-env \
activatecheck compatcheck compatsvc-check shortcutcheck launch-shell envcheck \
buildcheck settingscheck routecheck bridgecheck gamedrivecheck launchercheck \
- seedcheck gamefixescheck padcheck np-native-tests native-shim-tests \
+ seedcheck gamefixescheck cicheck padcheck np-native-tests native-shim-tests \
app-tests game-host-check dualsense-check steam-rumble-check
# app.yml runs the checks that need the built app in its build job and the rest in a
diff --git a/docs/RELEASING.md b/docs/RELEASING.md
index ea0b9de..7feafd1 100644
--- a/docs/RELEASING.md
+++ b/docs/RELEASING.md
@@ -43,7 +43,9 @@ a newer install and leaves it alone. `VersioningTests` guards both.
0. Push the changes first and wait for the `app` workflow to pass on them
(`gh run watch -R raymondchins/Bridgeplay`, about 10 minutes, free on this public repo).
- The release then reuses that result instead of running the checks again here.
+ The release then reuses that result instead of running the checks again here. A docs-only run
+ (the gate green, build and checks skipped) does not count; the release falls back to an older run
+ of the same sources or runs the checks here.
1. Bump and commit:
```sh
scripts/bump-version.sh patch # or minor / major
diff --git a/scripts/build-local.sh b/scripts/build-local.sh
index 8f3743e..1c3b220 100755
--- a/scripts/build-local.sh
+++ b/scripts/build-local.sh
@@ -237,18 +237,21 @@ if [ "$run_checks" -eq 1 ] && [ -n "$fingerprint" ] && [ "${BRIDGEPLAY_FORCE_CHE
checks_reused=1
fi
-# The app workflow runs the same make ci-checks on every push to main, so a release whose
-# sources (version.h aside) match a commit that workflow passed skips them too: push, let
-# CI pass, bump, release. Needs gh; without it, or with no passing run, the checks run here.
+# The app workflow runs the same make ci-checks on every push to main and beta, so a release
+# whose sources (version.h and docs aside) match a commit that workflow passed skips them
+# too: push, let CI pass, bump, release. Needs gh; without it, or with no passing run, the
+# checks run here. A docs-only run is green with its build and checks skipped, so a run
+# counts only when both jobs ran and succeeded (scripts/ci-run-passed.sh).
ci_slug=${BRIDGEPLAY_CI_REPO:-raymondchins/Bridgeplay}
ci_passed() {
command -v gh >/dev/null 2>&1 || return 1
for sha in $(git -C "$repo" rev-list --max-count=5 HEAD); do
- # app.yml skips pushes that only touch Markdown or docs/, so those don't count either.
- git -C "$repo" diff --quiet "$sha" HEAD -- . ':(exclude)dylib/version.h' \
- ':(exclude,glob)**/*.md' ':(exclude)docs' || continue
- gh run list -R "$ci_slug" -w app --commit "$sha" --status success --limit 1 \
- --json headSha -q '.[].headSha' 2>/dev/null | grep -q . && { echo "$sha"; return 0; }
+ # Only docs (.github/docs-only-paths) and version.h may differ from that commit.
+ # A failing step means "can't tell", never "same".
+ changed=$(git -C "$repo" -c core.quotePath=false diff --name-only --no-renames "$sha" HEAD) || continue
+ code=$(printf '%s\n' "$changed" | sh "$repo/scripts/ci-code-paths.sh") || continue
+ ! printf '%s' "$code" | grep -vqx 'dylib/version.h' || continue
+ sh "$repo/scripts/ci-run-passed.sh" "$ci_slug" "$sha" && { echo "$sha"; return 0; }
done
return 1
}
diff --git a/scripts/ci-code-paths.sh b/scripts/ci-code-paths.sh
new file mode 100755
index 0000000..77a03d9
--- /dev/null
+++ b/scripts/ci-code-paths.sh
@@ -0,0 +1,17 @@
+#!/bin/sh
+# Read changed paths on stdin, one per line, and print those that are not docs.
+# What counts as docs comes from .github/docs-only-paths (BRIDGEPLAY_DOCS_ONLY_FILE
+# points at another list). A missing list is an error, so no path is skipped by accident.
+patterns=${BRIDGEPLAY_DOCS_ONLY_FILE:-$(dirname "$0")/../.github/docs-only-paths}
+[ -f "$patterns" ] || { echo "ci-code-paths: $patterns not found" >&2; exit 2; }
+
+while IFS= read -r path || [ -n "$path" ]; do
+ [ -n "$path" ] || continue
+ docs=0
+ while IFS= read -r pattern || [ -n "$pattern" ]; do
+ case $pattern in '' | '#'*) continue ;; esac
+ # shellcheck disable=SC2254 # the pattern is data from the list, not a literal
+ case $path in $pattern) docs=1; break ;; esac
+ done <"$patterns"
+ [ "$docs" -eq 1 ] || printf '%s\n' "$path"
+done
diff --git a/scripts/ci-gate.sh b/scripts/ci-gate.sh
new file mode 100755
index 0000000..875fcec
--- /dev/null
+++ b/scripts/ci-gate.sh
@@ -0,0 +1,28 @@
+#!/bin/sh
+# The verdict of the app workflow's "app gate" job, the one check a branch rule requires.
+# Green only when the heavy jobs both succeeded, or both were skipped because the change
+# is docs-only. Failed, cancelled and any other skip are red: a required check that is
+# skipped counts as passing, so a skipped build must never be read as one.
+# SCOPE_RESULT needs.scope.result
+# DOCS_ONLY needs.scope.outputs.docs_only
+# BUILD_RESULT needs.build.result
+# CHECKS_RESULT needs.checks.result
+fail() {
+ echo "app gate: $*" >&2
+ exit 1
+}
+
+[ "${SCOPE_RESULT:-}" = success ] || fail "the change scope job ended ${SCOPE_RESULT:-with no result}"
+case ${DOCS_ONLY:-} in
+true) want=skipped ;;
+false) want=success ;;
+*) fail "docs_only is '${DOCS_ONLY:-}', not true or false" ;;
+esac
+[ "${BUILD_RESULT:-}" = "$want" ] || fail "full app build ended ${BUILD_RESULT:-with no result}, expected $want"
+[ "${CHECKS_RESULT:-}" = "$want" ] || fail "source checks ended ${CHECKS_RESULT:-with no result}, expected $want"
+
+if [ "$want" = skipped ]; then
+ echo "app gate: docs-only change, build and checks skipped"
+else
+ echo "app gate: full app build and source checks passed"
+fi
diff --git a/scripts/ci-run-passed.sh b/scripts/ci-run-passed.sh
new file mode 100755
index 0000000..c962093
--- /dev/null
+++ b/scripts/ci-run-passed.sh
@@ -0,0 +1,20 @@
+#!/bin/sh
+# ci-run-passed.sh <owner/repo> <sha>: exit 0 when the app workflow has a run on that commit
+# whose build and check jobs both ran and succeeded. A docs-only run is green too, with
+# those jobs skipped, so the run's own conclusion proves nothing about the sources.
+# The job names are the `name:` of the jobs in .github/workflows/app.yml.
+[ $# -eq 2 ] || { echo "usage: ci-run-passed.sh <owner/repo> <sha>" >&2; exit 2; }
+build_job=${BRIDGEPLAY_CI_BUILD_JOB:-full app build}
+checks_job=${BRIDGEPLAY_CI_CHECKS_JOB:-source checks}
+
+command -v gh >/dev/null 2>&1 || exit 1
+ids=$(gh run list -R "$1" -w app --commit "$2" --status success --limit 20 \
+ --json databaseId -q '.[].databaseId' 2>/dev/null) || exit 1
+for id in $ids; do
+ gh run view "$id" -R "$1" --json jobs -q '.jobs[] | [.name, .conclusion] | @tsv' 2>/dev/null |
+ awk -F '\t' -v b="$build_job" -v c="$checks_job" '
+ $1 == b && $2 == "success" { nb++ }
+ $1 == c && $2 == "success" { nc++ }
+ END { exit !(nb == 1 && nc == 1) }' && exit 0
+done
+exit 1
diff --git a/scripts/ci-scope.sh b/scripts/ci-scope.sh
new file mode 100755
index 0000000..67d7b8c
--- /dev/null
+++ b/scripts/ci-scope.sh
@@ -0,0 +1,35 @@
+#!/bin/sh
+# Print docs_only=true when the change under test touches only docs, docs_only=false
+# otherwise. Run from the checkout; the app workflow appends the line to $GITHUB_OUTPUT.
+# EVENT github.event_name
+# BEFORE github.event.before (push events)
+# Any doubt answers false and the whole workflow runs: another event, a new branch, a
+# base that can't be fetched, no changed files, an unreadable docs list.
+here=$(dirname "$0")
+
+changed_paths() {
+ case ${EVENT:-} in
+ pull_request)
+ # The checked-out merge commit: its first parent is the base, the second the PR head.
+ git rev-parse --verify -q 'HEAD^2' >/dev/null || return 1
+ git -c core.quotePath=false diff --name-only --no-renames 'HEAD^1' HEAD
+ ;;
+ push)
+ before=${BEFORE:-}
+ # All zeros: the first push of a branch has no earlier tip to compare with.
+ case $before in '' | *[!0]*) ;; *) return 1 ;; esac
+ git cat-file -e "$before^{commit}" 2>/dev/null ||
+ git fetch -q --no-tags --depth=1 origin "$before" || return 1
+ git -c core.quotePath=false diff --name-only --no-renames "$before" HEAD
+ ;;
+ *) return 1 ;;
+ esac
+}
+
+result=false
+if paths=$(changed_paths 2>/dev/null) && [ -n "$paths" ] &&
+ code=$(printf '%s\n' "$paths" | sh "$here/ci-code-paths.sh") && [ -z "$code" ]; then
+ result=true
+fi
+echo "ci-scope: ${EVENT:-no event}, docs_only=$result" >&2
+echo "docs_only=$result"
diff --git a/scripts/tests/cicheck.sh b/scripts/tests/cicheck.sh
new file mode 100644
index 0000000..7271790
--- /dev/null
+++ b/scripts/tests/cicheck.sh
@@ -0,0 +1,376 @@
+#!/bin/sh
+# cicheck: the always-running gate of .github/workflows/app.yml and the reuse of its runs.
+# - ci-code-paths.sh: which changed paths are docs (.github/docs-only-paths)
+# - ci-scope.sh: docs-only decision for push and pull_request events, on real git repos
+# - ci-gate.sh: every combination of job results, green only when it should be
+# - ci-run-passed.sh and build-local.sh's ci_passed: a run counts only if its heavy jobs ran
+# - the workflow files: triggers, job names, the gate's `if: always()`, concurrency
+# No network and no gh: gh is a stub.
+# shellcheck disable=SC2016 # the workflow lines checked below contain literal ${{ }} and $VAR
+set -u
+root=$(cd "$(dirname "$0")/../.." && pwd)
+work=$(mktemp -d)
+trap 'rm -rf "$work"' EXIT
+
+passed=0
+failed=0
+ok() { passed=$((passed + 1)); }
+bad() {
+ echo "FAIL: $*"
+ failed=$((failed + 1))
+}
+eq() { # eq <what> <expected> <actual>
+ if [ "$2" = "$3" ]; then ok; else bad "$1: expected '$2', got '$3'"; fi
+}
+yes() { # yes <what> <command...>: the command succeeds
+ what=$1
+ shift
+ if "$@" >/dev/null 2>&1; then ok; else bad "$what: expected success"; fi
+}
+no() { # no <what> <command...>: the command fails
+ what=$1
+ shift
+ if "$@" >/dev/null 2>&1; then bad "$what: expected failure"; else ok; fi
+}
+
+# --- ci-code-paths.sh --------------------------------------------------------------
+
+codes() { printf '%s\n' "$@" | sh "$root/scripts/ci-code-paths.sh"; }
+
+eq "docs only" "" "$(codes README.md docs/a/b.png compat/README.md a/b/c.md docs/x.md)"
+eq "code" "app/Sources/x.swift" "$(codes app/Sources/x.swift)"
+eq "mixed" "app/x.swift" "$(codes README.md app/x.swift docs/y.md)"
+eq "near misses are code" "docs
+docs.swift
+notes.mdx
+.github/docs-only-paths
+.github/workflows/app.yml
+dylib/version.h" "$(codes docs docs.swift notes.mdx .github/docs-only-paths .github/workflows/app.yml dylib/version.h)"
+eq "no input" "" "$(printf '' | sh "$root/scripts/ci-code-paths.sh")"
+eq "last line without a newline" "a.c" "$(printf 'x.md\na.c' | sh "$root/scripts/ci-code-paths.sh")"
+
+printf '# comment\n\n*.txt\n' >"$work/patterns"
+eq "other list: its pattern" "" "$(printf 'a.txt\n' | BRIDGEPLAY_DOCS_ONLY_FILE=$work/patterns sh "$root/scripts/ci-code-paths.sh")"
+eq "other list: the default is gone" "b.md" "$(printf 'b.md\n' | BRIDGEPLAY_DOCS_ONLY_FILE=$work/patterns sh "$root/scripts/ci-code-paths.sh")"
+eq "other list: comments are not patterns" "# comment" "$(printf '# comment\n' | BRIDGEPLAY_DOCS_ONLY_FILE=$work/patterns sh "$root/scripts/ci-code-paths.sh")"
+no "missing list is an error" sh -c "printf 'a.md\n' | BRIDGEPLAY_DOCS_ONLY_FILE=$work/none sh '$root/scripts/ci-code-paths.sh'"
+
+# --- ci-scope.sh -------------------------------------------------------------------
+
+gitq() { git -c user.name=cicheck -c [email protected] -c commit.gpgsign=false -c core.autocrlf=false "$@"; }
+new_repo() {
+ rm -rf "$work/r"
+ mkdir "$work/r"
+ cd "$work/r" || exit 1
+ git init -q
+ git config core.autocrlf false
+ git symbolic-ref HEAD refs/heads/main
+ mkdir app docs
+ echo a >app/a.c
+ echo r >README.md
+ echo d >docs/d.txt
+ git add -A
+ gitq commit -q -m base
+}
+commit() { # commit <msg> <file>...: change the files and commit
+ msg=$1
+ shift
+ for f in "$@"; do
+ mkdir -p "$(dirname "$f")"
+ echo "$msg" >>"$f"
+ done
+ git add -A
+ gitq commit -q -m "$msg"
+}
+scope() { # scope <event> [before]
+ (cd "$work/r" && EVENT=$1 BEFORE=${2:-} sh "$root/scripts/ci-scope.sh" 2>/dev/null)
+}
+
+new_repo
+base=$(git rev-parse HEAD)
+commit docs README.md docs/new.md
+eq "push, docs only" "docs_only=true" "$(scope push "$base")"
+commit code app/a.c
+eq "push, docs then code in one push" "docs_only=false" "$(scope push "$base")"
+second=$(git rev-parse HEAD)
+commit docs2 README.md
+eq "push, docs after code" "docs_only=true" "$(scope push "$second")"
+eq "push, the whole range has code" "docs_only=false" "$(scope push "$base")"
+commit mixed README.md app/b.c
+eq "push, docs and code in one commit" "docs_only=false" "$(scope push "$(git rev-parse HEAD~1)")"
+eq "push, new branch" "docs_only=false" "$(scope push 0000000000000000000000000000000000000000)"
+eq "push, no before" "docs_only=false" "$(scope push)"
+eq "push, before not in the repo" "docs_only=false" "$(scope push aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa)"
+eq "manual run" "docs_only=false" "$(scope workflow_dispatch "$base")"
+eq "no event" "docs_only=false" "$(scope '' "$base")"
+before=$(git rev-parse HEAD)
+gitq commit -q --allow-empty -m empty
+eq "push, nothing changed" "docs_only=false" "$(scope push "$before")"
+
+new_repo
+base=$(git rev-parse HEAD)
+git mv app/a.c app/a.md
+gitq commit -q -m rename
+eq "push, code renamed to a doc name" "docs_only=false" "$(scope push "$base")"
+new_repo
+base=$(git rev-parse HEAD)
+git rm -q app/a.c
+gitq commit -q -m delete
+eq "push, code deleted" "docs_only=false" "$(scope push "$base")"
+new_repo
+base=$(git rev-parse HEAD)
+commit docs README.md
+eq "push, list missing" "docs_only=false" \
+ "$(cd "$work/r" && BRIDGEPLAY_DOCS_ONLY_FILE=$work/none EVENT=push BEFORE=$base sh "$root/scripts/ci-scope.sh" 2>/dev/null)"
+new_repo
+base=$(git rev-parse HEAD)
+commit c app/a.c
+printf '*.c\n' >"$work/c-list"
+eq "push, other list" "docs_only=true" \
+ "$(cd "$work/r" && BRIDGEPLAY_DOCS_ONLY_FILE=$work/c-list EVENT=push BEFORE=$base sh "$root/scripts/ci-scope.sh" 2>/dev/null)"
+
+# A pull_request run checks out the merge commit: base first, PR head second.
+pr_merge() { # pr_merge <base-ref> <pr-branch>: leave HEAD on a merge of the PR into the base
+ git checkout -q -B merge "$1"
+ gitq merge -q --no-ff -m merge "$2"
+}
+new_repo
+git checkout -q -b pr
+commit docs README.md docs/x.md
+git checkout -q main
+pr_merge main pr
+eq "pull request, docs only" "docs_only=true" "$(scope pull_request)"
+new_repo
+git checkout -q -b pr
+commit code app/a.c
+pr_merge main pr
+eq "pull request, code" "docs_only=false" "$(scope pull_request)"
+new_repo
+git checkout -q -b pr
+commit docs README.md
+commit code app/b.c
+pr_merge main pr
+eq "pull request, docs and code" "docs_only=false" "$(scope pull_request)"
+new_repo
+git checkout -q -b pr
+commit docs README.md
+git checkout -q main
+commit "code on the base" app/a.c
+pr_merge main pr
+eq "pull request, the base moved on with code" "docs_only=true" "$(scope pull_request)"
+new_repo
+eq "pull request, HEAD is not a merge" "docs_only=false" "$(scope pull_request)"
+
+# --- ci-gate.sh --------------------------------------------------------------------
+
+gate() { SCOPE_RESULT=$1 DOCS_ONLY=$2 BUILD_RESULT=$3 CHECKS_RESULT=$4 sh "$root/scripts/ci-gate.sh"; }
+
+yes "gate: docs-only, heavy jobs skipped" gate success true skipped skipped
+yes "gate: code, heavy jobs passed" gate success false success success
+no "gate: code, build failed" gate success false failure success
+no "gate: code, checks failed" gate success false success failure
+no "gate: code, build cancelled" gate success false cancelled success
+no "gate: code, checks cancelled" gate success false success cancelled
+no "gate: code, heavy jobs skipped" gate success false skipped skipped
+no "gate: scope failed" gate failure '' skipped skipped
+no "gate: no results at all" env -u SCOPE_RESULT -u DOCS_ONLY -u BUILD_RESULT -u CHECKS_RESULT sh "$root/scripts/ci-gate.sh"
+
+# Every combination: green exactly for the two good ones.
+for s in success failure cancelled skipped; do
+ for d in true false ''; do
+ for b in success failure cancelled skipped; do
+ for c in success failure cancelled skipped; do
+ want=1
+ if [ "$s" = success ]; then
+ [ "$d $b $c" = "true skipped skipped" ] && want=0
+ [ "$d $b $c" = "false success success" ] && want=0
+ fi
+ gate "$s" "$d" "$b" "$c" >/dev/null 2>&1
+ eq "gate scope=$s docs_only=$d build=$b checks=$c" "$want" "$?"
+ done
+ done
+ done
+done
+
+# --- ci-run-passed.sh and ci_passed ------------------------------------------------
+
+mkdir "$work/bin" "$work/fake"
+cat >"$work/bin/gh" <<'EOF'
+#!/bin/sh
+# Stub: `gh run list` answers with fake/runs.<sha>, `gh run view <id>` with fake/jobs.<id>.
+echo "$*" >>"$FAKE_DIR/calls"
+case "$1 $2" in
+"run list")
+ sha=""
+ prev=""
+ for a in "$@"; do
+ [ "$prev" = --commit ] && sha=$a
+ prev=$a
+ done
+ [ ! -f "$FAKE_DIR/list-fails" ] || exit 1
+ cat "$FAKE_DIR/runs.$sha" 2>/dev/null
+ ;;
+"run view") cat "$FAKE_DIR/jobs.$3" 2>/dev/null || exit 1 ;;
+*) exit 1 ;;
+esac
+EOF
+chmod +x "$work/bin/gh"
+FAKE_DIR=$work/fake
+export FAKE_DIR
+tab=$(printf '\t')
+jobs_file() { # jobs_file <id> <scope> <build> <checks> <gate>
+ printf 'change scope%s%s\nfull app build%s%s\nsource checks%s%s\napp gate%s%s\n' \
+ "$tab" "$2" "$tab" "$3" "$tab" "$4" "$tab" "$5" >"$FAKE_DIR/jobs.$1"
+}
+reset_fake() { rm -f "$FAKE_DIR"/runs.* "$FAKE_DIR"/jobs.* "$FAKE_DIR/calls" "$FAKE_DIR/list-fails"; }
+passed_run() { PATH="$work/bin:$PATH" sh "$root/scripts/ci-run-passed.sh" owner/repo abc123; }
+
+reset_fake
+jobs_file 20 success success success success
+printf '20\n' >"$FAKE_DIR/runs.abc123"
+yes "run: both heavy jobs succeeded" passed_run
+if grep -q 'run list -R owner/repo -w app --commit abc123 --status success' "$FAKE_DIR/calls"; then ok; else bad "run: wrong gh run list query: $(cat "$FAKE_DIR/calls")"; fi
+
+reset_fake
+jobs_file 30 success skipped skipped success
+printf '30\n' >"$FAKE_DIR/runs.abc123"
+no "run: docs-only run, gate green but nothing built" passed_run
+
+jobs_file 20 success success success success
+printf '30\n20\n' >"$FAKE_DIR/runs.abc123"
+yes "run: newest is docs-only, an older full run counts" passed_run
+
+reset_fake
+jobs_file 20 success success failure failure
+printf '20\n' >"$FAKE_DIR/runs.abc123"
+no "run: checks failed" passed_run
+jobs_file 20 success skipped success success
+no "run: build skipped" passed_run
+jobs_file 20 success cancelled success success
+no "run: build cancelled" passed_run
+printf 'change scope\tsuccess\napp gate\tsuccess\n' >"$FAKE_DIR/jobs.20"
+no "run: heavy jobs absent" passed_run
+printf '' >"$FAKE_DIR/jobs.20"
+no "run: no job list" passed_run
+rm -f "$FAKE_DIR/jobs.20"
+no "run: job list unreadable" passed_run
+reset_fake
+no "run: no run for the commit" passed_run
+jobs_file 20 success success success success
+printf '20\n' >"$FAKE_DIR/runs.abc123"
+: >"$FAKE_DIR/list-fails"
+no "run: gh run list fails" passed_run
+no "run: wrong arguments" sh "$root/scripts/ci-run-passed.sh" owner/repo
+
+# ci_passed, the release's walk back over the last commits. Its helpers are the repo's own
+# scripts, copied beside a scratch history: c1 code, c2 docs, c3 the version bump.
+body=$(sed -n '/^ci_passed() {$/,/^}$/p' "$root/scripts/build-local.sh")
+if [ -z "$body" ]; then
+ bad "ci_passed not found in scripts/build-local.sh"
+else
+ eval "$body"
+ # shellcheck disable=SC2034 # read by the ci_passed body evaluated above
+ ci_slug=owner/repo
+ make_history() {
+ new_repo
+ repo=$work/r
+ # the copied helpers stay out of the history, or they would count as changes
+ printf 'scripts/\n.github/\n' >"$repo/.git/info/exclude"
+ mkdir -p "$repo/scripts" "$repo/.github" "$repo/dylib"
+ cp "$root"/scripts/ci-code-paths.sh "$root"/scripts/ci-run-passed.sh "$repo/scripts/"
+ cp "$root/.github/docs-only-paths" "$repo/.github/"
+ echo '#define V "0.7.0"' >"$repo/dylib/version.h"
+ git -C "$repo" add dylib/version.h
+ gitq -C "$repo" commit -q -m c1
+ c1=$(git -C "$repo" rev-parse HEAD)
+ cd "$repo" && commit "$1" "$2" && c2=$(git rev-parse HEAD)
+ echo '#define V "0.7.1"' >"$repo/dylib/version.h"
+ git -C "$repo" add dylib/version.h
+ gitq -C "$repo" commit -q -m c3
+ c3=$(git -C "$repo" rev-parse HEAD)
+ }
+ walk() { (PATH="$work/bin:$PATH" && ci_passed); }
+
+ reset_fake
+ jobs_file 11 success success success success
+ jobs_file 22 success skipped skipped success
+ make_history docs README.md
+ printf '11\n' >"$FAKE_DIR/runs.$c1"
+ printf '22\n' >"$FAKE_DIR/runs.$c2"
+ eq "ci_passed: the docs-only run is passed over for the full run behind it" "$c1" "$(walk)"
+
+ reset_fake
+ jobs_file 22 success skipped skipped success
+ jobs_file 11 success skipped skipped success
+ printf '11\n' >"$FAKE_DIR/runs.$c1"
+ printf '22\n' >"$FAKE_DIR/runs.$c2"
+ no "ci_passed: only docs-only runs, so the checks run locally" walk
+
+ reset_fake
+ jobs_file 33 success success success success
+ printf '33\n' >"$FAKE_DIR/runs.$c3"
+ eq "ci_passed: a full run on the bump commit itself" "$c3" "$(walk)"
+
+ reset_fake
+ make_history code app/a.c
+ jobs_file 11 success success success success
+ printf '11\n' >"$FAKE_DIR/runs.$c1"
+ no "ci_passed: code changed after the full run" walk
+
+ reset_fake
+ make_history docs README.md
+ jobs_file 11 success success success success
+ printf '11\n' >"$FAKE_DIR/runs.$c1"
+ rm "$repo/.github/docs-only-paths"
+ no "ci_passed: no docs list means can't tell, not same" walk
+fi
+cd "$root" || exit 1
+
+# --- the workflow files ------------------------------------------------------------
+
+app=$work/app.yml
+lint=$work/lint.yml
+tr -d '\r' <"$root/.github/workflows/app.yml" >"$app"
+tr -d '\r' <"$root/.github/workflows/lint.yml" >"$lint"
+job() { awk -v j=" $1:" '$0 == j { p = 1; next } p && /^ [a-z_-]+:$/ { exit } p' "$app"; }
+has() { printf '%s\n' "$2" | grep -Fxq -- "$1"; }
+
+no "app.yml: no path filters" grep -Eq '^[[:space:]]*paths(-ignore)?:' "$app"
+eq "app.yml: push branches" " branches: [main, beta]" "$(grep -E '^ branches:' "$app")"
+eq "lint.yml: push branches" " branches: [main, beta]" "$(grep -E '^ branches:' "$lint")"
+yes "app.yml: runs on every pull request" grep -Fxq ' pull_request:' "$app"
+no "app.yml: pull requests not limited to a branch" awk '/^ pull_request:/ { p = 1; next } p && /^ branches/ { f = 1 } p && /^ [a-z_]+:/ { p = 0 } END { exit !f }' "$app"
+yes "lint.yml: runs on every pull request" grep -Fxq ' pull_request:' "$lint"
+yes "app.yml: only PR runs are cancelled" grep -Fxq ' cancel-in-progress: ${{ github.event_name == '"'pull_request'"' }}' "$app"
+yes "app.yml: other runs have a group of their own" grep -Fxq ' group: app-${{ github.event_name == '"'pull_request'"' && github.ref || github.run_id }}' "$app"
+
+build=$(job build)
+checks=$(job checks)
+gate_job=$(job gate)
+scope_job=$(job scope)
+yes "build job name" has " name: full app build" "$build"
+yes "checks job name" has " name: source checks" "$checks"
+yes "gate job name" has " name: app gate" "$gate_job"
+eq "ci-run-passed.sh knows the build job" "full app build" "$(sed -n 's/^build_job=\${BRIDGEPLAY_CI_BUILD_JOB:-\(.*\)}$/\1/p' "$root/scripts/ci-run-passed.sh")"
+eq "ci-run-passed.sh knows the checks job" "source checks" "$(sed -n 's/^checks_job=\${BRIDGEPLAY_CI_CHECKS_JOB:-\(.*\)}$/\1/p' "$root/scripts/ci-run-passed.sh")"
+for j in build checks; do
+ body=$(job "$j")
+ yes "$j: waits for scope" has " needs: scope" "$body"
+ yes "$j: skipped for docs-only" has " if: needs.scope.outputs.docs_only != 'true'" "$body"
+done
+yes "gate: waits for every job" has " needs: [scope, build, checks]" "$gate_job"
+yes "gate: runs whatever the others did" has " if: always()" "$gate_job"
+yes "gate: on a Linux runner" has " runs-on: ubuntu-latest" "$gate_job"
+yes "gate: runs the verdict script" has " run: sh scripts/ci-gate.sh" "$gate_job"
+for v in 'SCOPE_RESULT: ${{ needs.scope.result }}' 'DOCS_ONLY: ${{ needs.scope.outputs.docs_only }}' \
+ 'BUILD_RESULT: ${{ needs.build.result }}' 'CHECKS_RESULT: ${{ needs.checks.result }}'; do
+ yes "gate input $v" has " $v" "$gate_job"
+done
+yes "scope: on a Linux runner" has " runs-on: ubuntu-latest" "$scope_job"
+yes "scope: sees the merge commit's parents" has " fetch-depth: 2" "$scope_job"
+yes "scope: runs the scope script into the job output" has ' run: sh scripts/ci-scope.sh | tee -a "$GITHUB_OUTPUT"' "$scope_job"
+yes "scope: output is docs_only" has ' docs_only: ${{ steps.scope.outputs.docs_only }}' "$scope_job"
+yes "build-local.sh reuses runs through ci-run-passed.sh" grep -q 'ci-run-passed.sh' "$root/scripts/build-local.sh"
+
+echo "cicheck: $passed passed, $failed failed"
+[ "$failed" -eq 0 ]