From 52fe3dc25306af0e421ade550c28acbfc57cf5b3 Mon Sep 17 00:00:00 2001 From: bitsandfoxes Date: Thu, 12 Nov 2026 14:29:29 +0100 Subject: [PATCH 1/8] feat(skip-ci): Add an action that skips CI for pushes changing only matching files --- .github/workflows/script-tests.yml | 10 ++ .github/workflows/workflow-tests.yml | 23 +++++ CHANGELOG.md | 6 ++ README.md | 6 ++ skip-ci/README.md | 78 +++++++++++++++ skip-ci/action.yml | 37 +++++++ skip-ci/scripts/match-paths.ps1 | 82 ++++++++++++++++ skip-ci/scripts/skip-ci.ps1 | 94 ++++++++++++++++++ skip-ci/tests/match-paths.Tests.ps1 | 60 ++++++++++++ skip-ci/tests/skip-ci.Tests.ps1 | 141 +++++++++++++++++++++++++++ 10 files changed, 537 insertions(+) create mode 100644 skip-ci/README.md create mode 100644 skip-ci/action.yml create mode 100644 skip-ci/scripts/match-paths.ps1 create mode 100644 skip-ci/scripts/skip-ci.ps1 create mode 100644 skip-ci/tests/match-paths.Tests.ps1 create mode 100644 skip-ci/tests/skip-ci.Tests.ps1 diff --git a/.github/workflows/script-tests.yml b/.github/workflows/script-tests.yml index 32a9027..cd04c76 100644 --- a/.github/workflows/script-tests.yml +++ b/.github/workflows/script-tests.yml @@ -28,6 +28,16 @@ jobs: env: GH_TOKEN: ${{ github.token }} + skip-ci: + name: Skip CI Tests + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4 + + - run: Invoke-Pester + working-directory: skip-ci + shell: pwsh + danger: name: Danger JS Tests runs-on: ubuntu-latest diff --git a/.github/workflows/workflow-tests.yml b/.github/workflows/workflow-tests.yml index b737ba1..0d45c48 100644 --- a/.github/workflows/workflow-tests.yml +++ b/.github/workflows/workflow-tests.yml @@ -157,6 +157,29 @@ jobs: Write-Host "✅ No-changes scenario validation passed!" + # A push is never a pull request update, so the action must tell the jobs to run. + skip-ci-push: + runs-on: ubuntu-latest + permissions: + actions: read + contents: read + steps: + - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4 + + - name: Run skip-ci action + id: skip-ci + uses: ./skip-ci + + - name: Validate output + shell: pwsh + env: + SKIP: ${{ steps.skip-ci.outputs.skip }} + run: | + if ($env:SKIP -ne 'false') { + Write-Error "Expected skip=false on push, got '$env:SKIP'" + exit 1 + } + cli-integration: runs-on: ${{ matrix.host }}-latest strategy: diff --git a/CHANGELOG.md b/CHANGELOG.md index 72bbc36..d1bee4b 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,11 @@ # Changelog +## Unreleased + +### Features + +- Skip CI - Add an action that tells whether a push to a pull request only changes files that need no CI, such as Markdown, since a head whose run passed. Jobs gated on its `skip` output don't run for a CHANGELOG fix-up. + ## 3.5.0 ### Features diff --git a/README.md b/README.md index 48f7a55..22782ac 100644 --- a/README.md +++ b/README.md @@ -22,6 +22,12 @@ Validates non-maintainer PRs against contribution guidelines and enforces draft **[📖 View full documentation →](validate-pr/README.md)** +### Skip CI + +Tells whether a push to a pull request only changes files that need no CI, such as Markdown, so expensive jobs can be skipped. + +**[📖 View full documentation →](skip-ci/README.md)** + ## Legacy Reusable Workflows (v2) > ⚠️ **Deprecated**: Reusable workflows have been converted to composite actions in v3. Please migrate to the composite actions above. diff --git a/skip-ci/README.md b/skip-ci/README.md new file mode 100644 index 0000000..03e36ab --- /dev/null +++ b/skip-ci/README.md @@ -0,0 +1,78 @@ +# Skip CI + +Tells whether a push to a pull request only changes files that need no CI, such as Markdown, since a head whose CI passed. Jobs gated on its `skip` output then don't run for a CHANGELOG fix-up or a docs edit, while everything else runs as usual. + +A workflow's `paths-ignore` can't do this: GitHub matches it against the whole pull request, so a pull request that changes code runs the full workflow on every later push, even one that only touches `CHANGELOG.md`. + +## Usage + +Add a job that runs the action, and gate the expensive jobs on its output: + +```yaml +jobs: + changes: + runs-on: ubuntu-latest + permissions: + actions: read + contents: read + outputs: + skip: ${{ steps.skip-ci.outputs.skip }} + steps: + - id: skip-ci + uses: getsentry/github-workflows/skip-ci@ + with: + paths: | + **/*.md + !package/** + + build: + needs: [changes] + if: ${{ needs.changes.outputs.skip != 'true' }} + runs-on: ubuntu-latest + steps: + - run: echo "build and test" +``` + +Pin to a specific commit SHA. Jobs that depend on a skipped job through `needs` skip with it, so gating the jobs everything else starts from is enough. Every job that waits on another one's artifacts must be gated too, or it waits for artifacts that never come. + +The job needs `actions: read` to find earlier runs and `contents: read` to compare commits. Without them the API calls fail, the action logs a warning, and CI runs. + +## Inputs + +| Input | Required | Description | +|-------|----------|-------------| +| `paths` | No | Patterns, one per line, of files whose changes alone need no CI. Default: `**/*.md`. | +| `api-token` | No | Token for the repo. Default: `${{ github.token }}`. | + +## Outputs + +| Output | Description | +|--------|-------------| +| `skip` | `true` when the jobs gated on this check can be skipped, `false` otherwise. | + +## When it skips + +`skip` is `true` only when all of these hold: + +- The workflow runs for a `pull_request` event with the `synchronize` action, i.e. a push to an open pull request. Any other event, including `push`, `workflow_dispatch`, `merge_group` and `pull_request_target`, gives `false`. +- The same workflow has a successful run for the previous head of the pull request, on the same branch of the same repository. A run that skipped its jobs through this action counts, because it was itself checked against a head that passed. +- The new head is strictly ahead of the previous head. A force-push that dropped or rewrote commits gives `false`. +- Between 1 and 299 files changed between the two heads (the compare API lists at most 300), and every changed file matches `paths`. For a renamed file, both its new and its old name must match. + +When any API call fails, the action logs a warning and gives `false`. It never fails the job. + +When it skips, the action writes the reason to the job summary. + +## Patterns + +- `**` matches any characters, including `/`. A leading `**/` also matches files at the root, so `**/*.md` matches `CHANGELOG.md` and `docs/setup.md`. +- `*` matches any characters except `/`, so `*.md` matches only Markdown files at the root. +- `?` matches one character except `/`. +- A pattern starting with `!` takes matching files back out. The last pattern that matches a file decides, so `!package/**` after `**/*.md` keeps Markdown files under `package/` needing CI. +- Blank lines and lines starting with `#` are ignored. Matching is case-sensitive. + +These are not GitHub's `paths` filter patterns: `?`, `+` and `[...]` mean something else there. + +## Required status checks + +A job skipped by its `if:` reports one check under its unexpanded name, such as `Build ${{ matrix.target }}`, instead of one per matrix entry. A required check that names a matrix entry then never reports, and the pull request can't be merged. If you require checks, require one job that always runs and checks the results of the others, not the gated jobs themselves. diff --git a/skip-ci/action.yml b/skip-ci/action.yml new file mode 100644 index 0000000..fe0aeef --- /dev/null +++ b/skip-ci/action.yml @@ -0,0 +1,37 @@ +name: 'Skip CI' +description: 'Tells whether a push to a pull request only changes files that need no CI, such as Markdown, since a head that passed' +author: 'Sentry' + +inputs: + paths: + description: 'Patterns, one per line, of files whose changes alone need no CI. A pattern starting with ! takes files back out; the last matching pattern wins.' + required: false + default: '**/*.md' + api-token: + description: 'Token for the repo. Needs `actions: read` and `contents: read`.' + required: false + default: ${{ github.token }} + +outputs: + skip: + description: "'true' when the jobs that depend on this check can be skipped; 'false' otherwise." + value: ${{ steps.check.outputs.skip }} + +runs: + using: 'composite' + steps: + - name: Check changes + id: check + shell: pwsh + env: + GH_TOKEN: ${{ inputs.api-token }} + PATHS: ${{ inputs.paths }} + EVENT_NAME: ${{ github.event_name }} + EVENT_ACTION: ${{ github.event.action }} + BEFORE: ${{ github.event.before }} + HEAD: ${{ github.event.pull_request.head.sha }} + HEAD_REF: ${{ github.event.pull_request.head.ref }} + HEAD_REPOSITORY: ${{ github.event.pull_request.head.repo.full_name }} + REPOSITORY: ${{ github.repository }} + WORKFLOW_REF: ${{ github.workflow_ref }} + run: ${{ github.action_path }}/scripts/skip-ci.ps1 diff --git a/skip-ci/scripts/match-paths.ps1 b/skip-ci/scripts/match-paths.ps1 new file mode 100644 index 0000000..53a6cbd --- /dev/null +++ b/skip-ci/scripts/match-paths.ps1 @@ -0,0 +1,82 @@ +# Returns $true when every file matches the patterns. +# A pattern starting with '!' takes matching files back out; the last pattern that matches a file decides. +# '**' matches any characters including '/', and a leading '**/' also matches files at the root; +# '*' matches any characters except '/'; '?' matches one character except '/'. Matching is case-sensitive. +param( + [Parameter(Mandatory = $true)][AllowEmptyCollection()][string[]] $Files, + [Parameter(Mandatory = $true)][AllowEmptyCollection()][AllowEmptyString()][string[]] $Patterns +) + +Set-StrictMode -Version latest + +function ConvertTo-Regex([string] $glob) +{ + $regex = '' + $i = 0 + while ($i -lt $glob.Length) + { + if ($glob.Substring($i).StartsWith('**/')) + { + $regex += '(?:.*/)?' + $i += 3 + } + elseif ($glob.Substring($i).StartsWith('**')) + { + $regex += '.*' + $i += 2 + } + elseif ($glob[$i] -eq '*') + { + $regex += '[^/]*' + $i++ + } + elseif ($glob[$i] -eq '?') + { + $regex += '[^/]' + $i++ + } + else + { + $regex += [regex]::Escape([string]$glob[$i]) + $i++ + } + } + "^$regex$" +} + +$rules = @(foreach ($pattern in $Patterns) + { + $pattern = $pattern.Trim() + if ($pattern -eq '' -or $pattern.StartsWith('#')) + { + continue + } + $exclude = $pattern.StartsWith('!') + if ($exclude) + { + $pattern = $pattern.Substring(1) + } + [pscustomobject]@{ Regex = ConvertTo-Regex $pattern; Exclude = $exclude } + }) + +if ($Files.Count -eq 0 -or $rules.Count -eq 0) +{ + return $false +} + +foreach ($file in $Files) +{ + $matched = $false + foreach ($rule in $rules) + { + if ($file -cmatch $rule.Regex) + { + $matched = -not $rule.Exclude + } + } + if (-not $matched) + { + return $false + } +} +return $true diff --git a/skip-ci/scripts/skip-ci.ps1 b/skip-ci/scripts/skip-ci.ps1 new file mode 100644 index 0000000..e45aab8 --- /dev/null +++ b/skip-ci/scripts/skip-ci.ps1 @@ -0,0 +1,94 @@ +# Decides whether a push to a pull request only changes files that don't need CI. +# Writes `skip=true` to GITHUB_OUTPUT only when all of these hold: +# - the event is `pull_request` with action `synchronize`; +# - the same workflow has a successful run for the previous head on the same PR branch; +# - the new head is strictly ahead of the previous head (no force-push dropped commits); +# - between 1 and 299 files changed, and every file (and the old name of a renamed file) matches `PATHS`. +# Any error leaves `skip=false`, so CI runs. The script always exits 0. + +Set-StrictMode -Version latest +$ErrorActionPreference = 'Stop' + +function Invoke-GhApi([string] $path) +{ + $json = gh api $path + if ($LASTEXITCODE -ne 0) + { + throw "gh api $path failed with exit code $LASTEXITCODE" + } + $json | ConvertFrom-Json +} + +function Get-SkipReason +{ + if ($env:EVENT_NAME -ne 'pull_request' -or $env:EVENT_ACTION -ne 'synchronize' -or -not $env:BEFORE) + { + Write-Host 'Not a push to an open pull request; CI runs.' + return $null + } + + # WORKFLOW_REF looks like 'owner/repo/.github/workflows/ci.yml@refs/pull/1/merge'. + # The runs API takes the file name; the full path returns 404. + $workflow = Split-Path -Leaf ($env:WORKFLOW_REF -replace '@.*$', '') + + $runs = Invoke-GhApi "repos/$env:REPOSITORY/actions/workflows/$workflow/runs?head_sha=$env:BEFORE&event=pull_request&status=success" + $passed = @($runs.workflow_runs | Where-Object { + $_.head_branch -eq $env:HEAD_REF -and $_.head_repository.full_name -eq $env:HEAD_REPOSITORY + }) + if ($passed.Count -eq 0) + { + Write-Host "$workflow has no successful run for the previous head $env:BEFORE; CI runs." + return $null + } + + # The compare API lists at most 300 files. + $compare = Invoke-GhApi "repos/$env:REPOSITORY/compare/$env:BEFORE...$env:HEAD" + $files = @($compare.files) + if ($compare.status -ne 'ahead' -or $files.Count -eq 0 -or $files.Count -ge 300) + { + Write-Host "Comparing $env:BEFORE...$env:HEAD gives status '$($compare.status)' with $($files.Count) files; CI runs." + return $null + } + + $names = @(foreach ($file in $files) + { + $file.filename + if ($file.PSObject.Properties['previous_filename']) + { + $file.previous_filename + } + }) + $patterns = @($env:PATHS -split "`n") + if (-not (& "$PSScriptRoot/match-paths.ps1" -Files $names -Patterns $patterns)) + { + Write-Host "Some files changed since $env:BEFORE don't match ``paths``; CI runs." + return $null + } + + "Only files matching ``paths`` changed since $env:BEFORE, which passed $workflow." +} + +$skip = $false +try +{ + $reason = Get-SkipReason + if ($reason) + { + $skip = $true + Write-Host $reason + if ($env:GITHUB_STEP_SUMMARY) + { + "$reason Skipping the jobs that depend on it." | Out-File $env:GITHUB_STEP_SUMMARY -Append + } + } +} +catch +{ + Write-Host "::warning::Couldn't check the changes, so CI runs: $_" +} + +if ($env:GITHUB_OUTPUT) +{ + "skip=$($skip.ToString().ToLower())" | Out-File $env:GITHUB_OUTPUT -Append +} +exit 0 diff --git a/skip-ci/tests/match-paths.Tests.ps1 b/skip-ci/tests/match-paths.Tests.ps1 new file mode 100644 index 0000000..fca8b93 --- /dev/null +++ b/skip-ci/tests/match-paths.Tests.ps1 @@ -0,0 +1,60 @@ +BeforeAll { + function MatchPaths([string[]] $Files, [string[]] $Patterns) + { + & "$PSScriptRoot/../scripts/match-paths.ps1" -Files $Files -Patterns $Patterns + } +} + +Describe 'match-paths' { + It '**/*.md matches Markdown at the root and in folders' { + MatchPaths @('CHANGELOG.md', 'docs/a.md', 'a/b/c.md') @('**/*.md') | Should -BeTrue + } + + It 'fails when one file does not match' { + MatchPaths @('CHANGELOG.md', 'src/a.cs') @('**/*.md') | Should -BeFalse + } + + It '* does not cross folders' { + MatchPaths @('README.md') @('*.md') | Should -BeTrue + MatchPaths @('docs/a.md') @('*.md') | Should -BeFalse + } + + It '** without a slash crosses folders' { + MatchPaths @('README.md', 'docs/a.md') @('**.md') | Should -BeTrue + MatchPaths @('docs/a/b.png') @('docs/**') | Should -BeTrue + } + + It '? matches one character' { + MatchPaths @('a1.md') @('a?.md') | Should -BeTrue + MatchPaths @('a12.md') @('a?.md') | Should -BeFalse + } + + It 'treats dots and other regex characters literally' { + MatchPaths @('README_md') @('*.md') | Should -BeFalse + MatchPaths @('a+b.md') @('a+b.md') | Should -BeTrue + } + + It 'matches case-sensitively' { + MatchPaths @('README.MD') @('**/*.md') | Should -BeFalse + } + + It '! takes files back out' { + $patterns = @('**/*.md', '!package*/**') + MatchPaths @('README.md') $patterns | Should -BeTrue + MatchPaths @('package/README.md') $patterns | Should -BeFalse + MatchPaths @('package-dev/Documentation~/index.md') $patterns | Should -BeFalse + } + + It 'the last matching pattern wins' { + MatchPaths @('docs/keep.md') @('**/*.md', '!docs/**', 'docs/keep.md') | Should -BeTrue + } + + It 'ignores blank lines and comments' { + MatchPaths @('README.md') @('', '# docs', ' **/*.md ') | Should -BeTrue + } + + It 'never matches without files or patterns' { + MatchPaths @() @('**/*.md') | Should -BeFalse + MatchPaths @('README.md') @('', '# only a comment') | Should -BeFalse + } +} diff --git a/skip-ci/tests/skip-ci.Tests.ps1 b/skip-ci/tests/skip-ci.Tests.ps1 new file mode 100644 index 0000000..cfa6b3f --- /dev/null +++ b/skip-ci/tests/skip-ci.Tests.ps1 @@ -0,0 +1,141 @@ +BeforeAll { + # Stands in for the gh CLI: answers `gh api ` from $global:GhResponses, keyed by path prefix. + function gh + { + $path = $args[1] + $global:GhCalls += $path + foreach ($key in $global:GhResponses.Keys) + { + if ($path.StartsWith($key)) + { + $global:LASTEXITCODE = 0 + return ($global:GhResponses[$key] | ConvertTo-Json -Depth 10) + } + } + $global:LASTEXITCODE = 1 + Write-Error "HTTP 404: Not Found ($path)" -ErrorAction Continue + } + + # Runs the script and fails the test if it hit an unexpected error. + function Invoke-SkipCiChecked + { + $result = Invoke-SkipCi + $result.Log | Should -Not -Match '::warning::' + $result + } + + function Invoke-SkipCi + { + $output = New-TemporaryFile + $summary = New-TemporaryFile + $env:GITHUB_OUTPUT = $output + $env:GITHUB_STEP_SUMMARY = $summary + try + { + $log = & "$PSScriptRoot/../scripts/skip-ci.ps1" *>&1 | Out-String + [pscustomobject]@{ + Log = $log + Output = (Get-Content $output -Raw).Trim() + Summary = Get-Content $summary -Raw + ExitCode = $LASTEXITCODE + } + } + finally + { + Remove-Item $output, $summary + } + } + + $runsPath = 'repos/getsentry/repo/actions/workflows/ci.yml/runs?head_sha=before&event=pull_request&status=success' + $comparePath = 'repos/getsentry/repo/compare/before...head' +} + +Describe 'skip-ci' { + AfterAll { + Remove-Variable GhCalls, GhResponses -Scope Global + } + + BeforeEach { + $env:EVENT_NAME = 'pull_request' + $env:EVENT_ACTION = 'synchronize' + $env:BEFORE = 'before' + $env:HEAD = 'head' + $env:HEAD_REF = 'feat/x' + $env:HEAD_REPOSITORY = 'getsentry/repo' + $env:REPOSITORY = 'getsentry/repo' + $env:WORKFLOW_REF = 'getsentry/repo/.github/workflows/ci.yml@refs/pull/1/merge' + $env:PATHS = "**/*.md`n!package/**" + $global:GhCalls = @() + $global:GhResponses = @{ + $runsPath = @{ workflow_runs = @(@{ head_branch = 'feat/x'; head_repository = @{ full_name = 'getsentry/repo' } }) } + $comparePath = @{ status = 'ahead'; files = @(@{ filename = 'CHANGELOG.md' }, @{ filename = 'docs/a.md' }) } + } + } + + It 'skips when only matching files changed since a passing head' { + $result = Invoke-SkipCiChecked + $result.Output | Should -Be 'skip=true' + $result.Summary | Should -Match 'before' + $result.ExitCode | Should -Be 0 + $global:GhCalls | Should -Be @($runsPath, $comparePath) + } + + It 'runs when a file does not match' { + $global:GhResponses[$comparePath].files += @{ filename = 'src/a.cs' } + (Invoke-SkipCiChecked).Output | Should -Be 'skip=false' + } + + It 'runs when a code file was renamed to a matching name' { + $global:GhResponses[$comparePath].files = @(@{ filename = 'a.md'; previous_filename = 'a.cs' }) + (Invoke-SkipCiChecked).Output | Should -Be 'skip=false' + } + + It 'runs when an excluded file changed' { + $global:GhResponses[$comparePath].files = @(@{ filename = 'package/README.md' }) + (Invoke-SkipCiChecked).Output | Should -Be 'skip=false' + } + + It 'runs when the previous head has no successful run' { + $global:GhResponses[$runsPath].workflow_runs = @() + (Invoke-SkipCiChecked).Output | Should -Be 'skip=false' + $global:GhCalls | Should -Be @($runsPath) + } + + It 'runs when the only successful run is for another branch or fork' { + $global:GhResponses[$runsPath].workflow_runs = @( + @{ head_branch = 'other'; head_repository = @{ full_name = 'getsentry/repo' } }, + @{ head_branch = 'feat/x'; head_repository = @{ full_name = 'someone/repo' } }) + (Invoke-SkipCiChecked).Output | Should -Be 'skip=false' + } + + It 'runs when the new head is not strictly ahead' -TestCases @( + @{ Status = 'diverged' }, @{ Status = 'behind' }, @{ Status = 'identical' }) { + $global:GhResponses[$comparePath].status = $Status + (Invoke-SkipCiChecked).Output | Should -Be 'skip=false' + } + + It 'runs when no files or 300 files are listed' { + $global:GhResponses[$comparePath].files = @() + (Invoke-SkipCiChecked).Output | Should -Be 'skip=false' + $global:GhResponses[$comparePath].files = @(1..300 | ForEach-Object { @{ filename = "$_.md" } }) + (Invoke-SkipCiChecked).Output | Should -Be 'skip=false' + } + + It 'runs for other events and actions' -TestCases @( + @{ Name = 'push'; Action = '' }, + @{ Name = 'pull_request'; Action = 'opened' }, + @{ Name = 'pull_request_target'; Action = 'synchronize' }) { + $env:EVENT_NAME = $Name + $env:EVENT_ACTION = $Action + (Invoke-SkipCiChecked).Output | Should -Be 'skip=false' + $global:GhCalls | Should -BeNullOrEmpty + } + + It 'runs and exits 0 when the API fails' { + $global:GhResponses.Remove($comparePath) + $result = Invoke-SkipCi + $result.Output | Should -Be 'skip=false' + $result.ExitCode | Should -Be 0 + $result.Log | Should -Match '::warning::' + } +} From b98144a4edce042b978e06ef0f6173ab8e0dd4ec Mon Sep 17 00:00:00 2001 From: bitsandfoxes Date: Fri, 13 Nov 2026 10:09:16 +0100 Subject: [PATCH 2/8] fix(skip-ci): Match the passing run to the pull request and use Pester mocks --- skip-ci/README.md | 6 +- skip-ci/action.yml | 1 + skip-ci/scripts/skip-ci.ps1 | 6 +- skip-ci/tests/skip-ci.Tests.ps1 | 103 +++++++++++++++----------------- 4 files changed, 59 insertions(+), 57 deletions(-) diff --git a/skip-ci/README.md b/skip-ci/README.md index 03e36ab..da8ddd1 100644 --- a/skip-ci/README.md +++ b/skip-ci/README.md @@ -55,10 +55,14 @@ The job needs `actions: read` to find earlier runs and `contents: read` to compa `skip` is `true` only when all of these hold: - The workflow runs for a `pull_request` event with the `synchronize` action, i.e. a push to an open pull request. Any other event, including `push`, `workflow_dispatch`, `merge_group` and `pull_request_target`, gives `false`. -- The same workflow has a successful run for the previous head of the pull request, on the same branch of the same repository. A run that skipped its jobs through this action counts, because it was itself checked against a head that passed. +- The same workflow has a successful run for the previous head of the same pull request. Runs for pull requests from forks don't name their pull request, so for those the run must be on the same branch of the same fork. A run that skipped its jobs through this action counts, because it was itself checked against a head that passed. - The new head is strictly ahead of the previous head. A force-push that dropped or rewrote commits gives `false`. - Between 1 and 299 files changed between the two heads (the compare API lists at most 300), and every changed file matches `paths`. For a renamed file, both its new and its old name must match. +A successful run is all the action checks: it doesn't know whether the gated jobs ran in it. If those jobs have conditions of their own, such as skipping drafts, a run where they didn't run still lets the next push skip. + +A skipped run also doesn't test the pull request against a base branch that moved since the passing run. Require branches to be up to date before merging, or use a merge queue, if that matters. + When any API call fails, the action logs a warning and gives `false`. It never fails the job. When it skips, the action writes the reason to the job summary. diff --git a/skip-ci/action.yml b/skip-ci/action.yml index fe0aeef..d41be7d 100644 --- a/skip-ci/action.yml +++ b/skip-ci/action.yml @@ -31,6 +31,7 @@ runs: BEFORE: ${{ github.event.before }} HEAD: ${{ github.event.pull_request.head.sha }} HEAD_REF: ${{ github.event.pull_request.head.ref }} + PR_NUMBER: ${{ github.event.pull_request.number }} HEAD_REPOSITORY: ${{ github.event.pull_request.head.repo.full_name }} REPOSITORY: ${{ github.repository }} WORKFLOW_REF: ${{ github.workflow_ref }} diff --git a/skip-ci/scripts/skip-ci.ps1 b/skip-ci/scripts/skip-ci.ps1 index e45aab8..6eaaf2f 100644 --- a/skip-ci/scripts/skip-ci.ps1 +++ b/skip-ci/scripts/skip-ci.ps1 @@ -1,7 +1,7 @@ # Decides whether a push to a pull request only changes files that don't need CI. # Writes `skip=true` to GITHUB_OUTPUT only when all of these hold: # - the event is `pull_request` with action `synchronize`; -# - the same workflow has a successful run for the previous head on the same PR branch; +# - the same workflow has a successful run for the previous head of the same pull request; # - the new head is strictly ahead of the previous head (no force-push dropped commits); # - between 1 and 299 files changed, and every file (and the old name of a renamed file) matches `PATHS`. # Any error leaves `skip=false`, so CI runs. The script always exits 0. @@ -32,8 +32,10 @@ function Get-SkipReason $workflow = Split-Path -Leaf ($env:WORKFLOW_REF -replace '@.*$', '') $runs = Invoke-GhApi "repos/$env:REPOSITORY/actions/workflows/$workflow/runs?head_sha=$env:BEFORE&event=pull_request&status=success" + # A run lists the pull requests it ran for, except for pull requests from forks, which list none. $passed = @($runs.workflow_runs | Where-Object { - $_.head_branch -eq $env:HEAD_REF -and $_.head_repository.full_name -eq $env:HEAD_REPOSITORY + $_.head_branch -eq $env:HEAD_REF -and $_.head_repository.full_name -eq $env:HEAD_REPOSITORY -and + (@($_.pull_requests).Count -eq 0 -or @($_.pull_requests | Where-Object { "$($_.number)" -eq $env:PR_NUMBER }).Count -gt 0) }) if ($passed.Count -eq 0) { diff --git a/skip-ci/tests/skip-ci.Tests.ps1 b/skip-ci/tests/skip-ci.Tests.ps1 index cfa6b3f..3502029 100644 --- a/skip-ci/tests/skip-ci.Tests.ps1 +++ b/skip-ci/tests/skip-ci.Tests.ps1 @@ -1,28 +1,6 @@ BeforeAll { - # Stands in for the gh CLI: answers `gh api ` from $global:GhResponses, keyed by path prefix. - function gh - { - $path = $args[1] - $global:GhCalls += $path - foreach ($key in $global:GhResponses.Keys) - { - if ($path.StartsWith($key)) - { - $global:LASTEXITCODE = 0 - return ($global:GhResponses[$key] | ConvertTo-Json -Depth 10) - } - } - $global:LASTEXITCODE = 1 - Write-Error "HTTP 404: Not Found ($path)" -ErrorAction Continue - } - - # Runs the script and fails the test if it hit an unexpected error. - function Invoke-SkipCiChecked - { - $result = Invoke-SkipCi - $result.Log | Should -Not -Match '::warning::' - $result - } + $runsPath = 'repos/getsentry/repo/actions/workflows/ci.yml/runs?head_sha=before&event=pull_request&status=success' + $comparePath = 'repos/getsentry/repo/compare/before...head' function Invoke-SkipCi { @@ -46,15 +24,16 @@ BeforeAll { } } - $runsPath = 'repos/getsentry/repo/actions/workflows/ci.yml/runs?head_sha=before&event=pull_request&status=success' - $comparePath = 'repos/getsentry/repo/compare/before...head' + # Runs the script and fails the test if it hit an unexpected error. + function Invoke-SkipCiChecked + { + $result = Invoke-SkipCi + $result.Log | Should -Not -Match '::warning::' + $result + } } Describe 'skip-ci' { - AfterAll { - Remove-Variable GhCalls, GhResponses -Scope Global - } - BeforeEach { $env:EVENT_NAME = 'pull_request' $env:EVENT_ACTION = 'synchronize' @@ -62,14 +41,20 @@ Describe 'skip-ci' { $env:HEAD = 'head' $env:HEAD_REF = 'feat/x' $env:HEAD_REPOSITORY = 'getsentry/repo' + $env:PR_NUMBER = '1' $env:REPOSITORY = 'getsentry/repo' $env:WORKFLOW_REF = 'getsentry/repo/.github/workflows/ci.yml@refs/pull/1/merge' $env:PATHS = "**/*.md`n!package/**" - $global:GhCalls = @() - $global:GhResponses = @{ - $runsPath = @{ workflow_runs = @(@{ head_branch = 'feat/x'; head_repository = @{ full_name = 'getsentry/repo' } }) } - $comparePath = @{ status = 'ahead'; files = @(@{ filename = 'CHANGELOG.md' }, @{ filename = 'docs/a.md' }) } - } + + $runs = @{ workflow_runs = @(@{ + head_branch = 'feat/x' + head_repository = @{ full_name = 'getsentry/repo' } + pull_requests = @(@{ number = 1 }) + }) } + $compare = @{ status = 'ahead'; files = @(@{ filename = 'CHANGELOG.md' }, @{ filename = 'docs/a.md' }) } + + Mock gh { $global:LASTEXITCODE = 0; $runs | ConvertTo-Json -Depth 10 } -ParameterFilter { $args[1] -eq $runsPath } + Mock gh { $global:LASTEXITCODE = 0; $compare | ConvertTo-Json -Depth 10 } -ParameterFilter { $args[1] -eq $comparePath } } It 'skips when only matching files changed since a passing head' { @@ -77,62 +62,72 @@ Describe 'skip-ci' { $result.Output | Should -Be 'skip=true' $result.Summary | Should -Match 'before' $result.ExitCode | Should -Be 0 - $global:GhCalls | Should -Be @($runsPath, $comparePath) + Should -Invoke gh -Times 1 -Exactly -ParameterFilter { $args[1] -eq $runsPath } + Should -Invoke gh -Times 1 -Exactly -ParameterFilter { $args[1] -eq $comparePath } + } + + It 'skips when the passing run is for a fork, which lists no pull requests' { + $env:HEAD_REPOSITORY = 'someone/repo' + $runs.workflow_runs = @(@{ head_branch = 'feat/x'; head_repository = @{ full_name = 'someone/repo' }; pull_requests = @() }) + (Invoke-SkipCiChecked).Output | Should -Be 'skip=true' } It 'runs when a file does not match' { - $global:GhResponses[$comparePath].files += @{ filename = 'src/a.cs' } + $compare.files += @{ filename = 'src/a.cs' } (Invoke-SkipCiChecked).Output | Should -Be 'skip=false' } It 'runs when a code file was renamed to a matching name' { - $global:GhResponses[$comparePath].files = @(@{ filename = 'a.md'; previous_filename = 'a.cs' }) + $compare.files = @(@{ filename = 'a.md'; previous_filename = 'a.cs' }) (Invoke-SkipCiChecked).Output | Should -Be 'skip=false' } It 'runs when an excluded file changed' { - $global:GhResponses[$comparePath].files = @(@{ filename = 'package/README.md' }) + $compare.files = @(@{ filename = 'package/README.md' }) (Invoke-SkipCiChecked).Output | Should -Be 'skip=false' } It 'runs when the previous head has no successful run' { - $global:GhResponses[$runsPath].workflow_runs = @() + $runs.workflow_runs = @() (Invoke-SkipCiChecked).Output | Should -Be 'skip=false' - $global:GhCalls | Should -Be @($runsPath) + Should -Invoke gh -Times 0 -ParameterFilter { $args[1] -eq $comparePath } } - It 'runs when the only successful run is for another branch or fork' { - $global:GhResponses[$runsPath].workflow_runs = @( - @{ head_branch = 'other'; head_repository = @{ full_name = 'getsentry/repo' } }, - @{ head_branch = 'feat/x'; head_repository = @{ full_name = 'someone/repo' } }) + It 'runs when the only successful run is for another ' -TestCases @( + @{ Case = 'branch'; Branch = 'other'; Repository = 'getsentry/repo'; Number = 1 }, + @{ Case = 'fork'; Branch = 'feat/x'; Repository = 'someone/repo'; Number = 1 }, + @{ Case = 'pull request'; Branch = 'feat/x'; Repository = 'getsentry/repo'; Number = 2 }) { + $runs.workflow_runs = @(@{ + head_branch = $Branch + head_repository = @{ full_name = $Repository } + pull_requests = @(@{ number = $Number }) + }) (Invoke-SkipCiChecked).Output | Should -Be 'skip=false' } - It 'runs when the new head is not strictly ahead' -TestCases @( + It 'runs when the new head is ' -TestCases @( @{ Status = 'diverged' }, @{ Status = 'behind' }, @{ Status = 'identical' }) { - $global:GhResponses[$comparePath].status = $Status + $compare.status = $Status (Invoke-SkipCiChecked).Output | Should -Be 'skip=false' } - It 'runs when no files or 300 files are listed' { - $global:GhResponses[$comparePath].files = @() - (Invoke-SkipCiChecked).Output | Should -Be 'skip=false' - $global:GhResponses[$comparePath].files = @(1..300 | ForEach-Object { @{ filename = "$_.md" } }) + It 'runs when files are listed' -TestCases @(@{ Count = 0 }, @{ Count = 300 }) { + $compare.files = @(1..$Count | Where-Object { $Count -gt 0 } | ForEach-Object { @{ filename = "$_.md" } }) (Invoke-SkipCiChecked).Output | Should -Be 'skip=false' } - It 'runs for other events and actions' -TestCases @( + It 'runs for ' -TestCases @( @{ Name = 'push'; Action = '' }, @{ Name = 'pull_request'; Action = 'opened' }, @{ Name = 'pull_request_target'; Action = 'synchronize' }) { $env:EVENT_NAME = $Name $env:EVENT_ACTION = $Action (Invoke-SkipCiChecked).Output | Should -Be 'skip=false' - $global:GhCalls | Should -BeNullOrEmpty + Should -Invoke gh -Times 0 } It 'runs and exits 0 when the API fails' { - $global:GhResponses.Remove($comparePath) + Mock gh { $global:LASTEXITCODE = 1; Write-Error 'HTTP 404: Not Found' -ErrorAction Continue } -ParameterFilter { $args[1] -eq $comparePath } $result = Invoke-SkipCi $result.Output | Should -Be 'skip=false' $result.ExitCode | Should -Be 0 From 387b2d2612b63b217b5a4d43e40a9072c0fb6afd Mon Sep 17 00:00:00 2001 From: bitsandfoxes Date: Fri, 13 Nov 2026 10:10:53 +0100 Subject: [PATCH 3/8] docs(skip-ci): Say which runs count for a pull request --- skip-ci/README.md | 2 +- skip-ci/scripts/skip-ci.ps1 | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/skip-ci/README.md b/skip-ci/README.md index da8ddd1..c176106 100644 --- a/skip-ci/README.md +++ b/skip-ci/README.md @@ -55,7 +55,7 @@ The job needs `actions: read` to find earlier runs and `contents: read` to compa `skip` is `true` only when all of these hold: - The workflow runs for a `pull_request` event with the `synchronize` action, i.e. a push to an open pull request. Any other event, including `push`, `workflow_dispatch`, `merge_group` and `pull_request_target`, gives `false`. -- The same workflow has a successful run for the previous head of the same pull request. Runs for pull requests from forks don't name their pull request, so for those the run must be on the same branch of the same fork. A run that skipped its jobs through this action counts, because it was itself checked against a head that passed. +- The same workflow has a successful run for the previous head, on the same branch of the same repository, that lists this pull request. A run lists every open pull request with that head, so when two pull requests share a branch, such as one into `main` and one into a release branch, a run that passed for one counts for the other. Runs for pull requests from forks list none, so for those the branch and fork must match. A run that skipped its jobs through this action counts, because it was itself checked against a head that passed. - The new head is strictly ahead of the previous head. A force-push that dropped or rewrote commits gives `false`. - Between 1 and 299 files changed between the two heads (the compare API lists at most 300), and every changed file matches `paths`. For a renamed file, both its new and its old name must match. diff --git a/skip-ci/scripts/skip-ci.ps1 b/skip-ci/scripts/skip-ci.ps1 index 6eaaf2f..c3a6eac 100644 --- a/skip-ci/scripts/skip-ci.ps1 +++ b/skip-ci/scripts/skip-ci.ps1 @@ -1,7 +1,7 @@ # Decides whether a push to a pull request only changes files that don't need CI. # Writes `skip=true` to GITHUB_OUTPUT only when all of these hold: # - the event is `pull_request` with action `synchronize`; -# - the same workflow has a successful run for the previous head of the same pull request; +# - the same workflow has a successful run for the previous head that lists this pull request; # - the new head is strictly ahead of the previous head (no force-push dropped commits); # - between 1 and 299 files changed, and every file (and the old name of a renamed file) matches `PATHS`. # Any error leaves `skip=false`, so CI runs. The script always exits 0. @@ -32,7 +32,7 @@ function Get-SkipReason $workflow = Split-Path -Leaf ($env:WORKFLOW_REF -replace '@.*$', '') $runs = Invoke-GhApi "repos/$env:REPOSITORY/actions/workflows/$workflow/runs?head_sha=$env:BEFORE&event=pull_request&status=success" - # A run lists the pull requests it ran for, except for pull requests from forks, which list none. + # A run lists every open pull request with its head, not only the one it ran for; runs for forks list none. $passed = @($runs.workflow_runs | Where-Object { $_.head_branch -eq $env:HEAD_REF -and $_.head_repository.full_name -eq $env:HEAD_REPOSITORY -and (@($_.pull_requests).Count -eq 0 -or @($_.pull_requests | Where-Object { "$($_.number)" -eq $env:PR_NUMBER }).Count -gt 0) From 0fe277df7f0b9b5fa61d6f6ab54937962fb843ce Mon Sep 17 00:00:00 2001 From: bitsandfoxes Date: Tue, 17 Nov 2026 15:46:48 +0100 Subject: [PATCH 4/8] docs(skip-ci): Say the action needs gh and pwsh on the runner --- skip-ci/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/skip-ci/README.md b/skip-ci/README.md index c176106..2d83595 100644 --- a/skip-ci/README.md +++ b/skip-ci/README.md @@ -35,7 +35,7 @@ jobs: Pin to a specific commit SHA. Jobs that depend on a skipped job through `needs` skip with it, so gating the jobs everything else starts from is enough. Every job that waits on another one's artifacts must be gated too, or it waits for artifacts that never come. -The job needs `actions: read` to find earlier runs and `contents: read` to compare commits. Without them the API calls fail, the action logs a warning, and CI runs. +The job needs `actions: read` to find earlier runs and `contents: read` to compare commits. Without them the API calls fail, the action logs a warning, and CI runs. The action runs `gh` and `pwsh`, which GitHub-hosted runners have. On a runner without `gh`, it logs a warning and gives `false`, so CI runs; on a runner without `pwsh`, the step fails, and so do the jobs that need it. ## Inputs From 61b885ac883524c74b4cec06aa6681ae4dd21a41 Mon Sep 17 00:00:00 2001 From: bitsandfoxes Date: Tue, 17 Nov 2026 15:48:06 +0100 Subject: [PATCH 5/8] docs(skip-ci): Say the jobs that need a failed check don't run --- skip-ci/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/skip-ci/README.md b/skip-ci/README.md index 2d83595..117ef77 100644 --- a/skip-ci/README.md +++ b/skip-ci/README.md @@ -35,7 +35,7 @@ jobs: Pin to a specific commit SHA. Jobs that depend on a skipped job through `needs` skip with it, so gating the jobs everything else starts from is enough. Every job that waits on another one's artifacts must be gated too, or it waits for artifacts that never come. -The job needs `actions: read` to find earlier runs and `contents: read` to compare commits. Without them the API calls fail, the action logs a warning, and CI runs. The action runs `gh` and `pwsh`, which GitHub-hosted runners have. On a runner without `gh`, it logs a warning and gives `false`, so CI runs; on a runner without `pwsh`, the step fails, and so do the jobs that need it. +The job needs `actions: read` to find earlier runs and `contents: read` to compare commits. Without them the API calls fail, the action logs a warning, and CI runs. The action runs `gh` and `pwsh`, which GitHub-hosted runners have. On a runner without `gh`, it logs a warning and gives `false`, so CI runs; on a runner without `pwsh`, the step fails, and the jobs that need it don't run. ## Inputs From 4c355f5274d05aa9ccd38842a06668ce345fb5f8 Mon Sep 17 00:00:00 2001 From: bitsandfoxes Date: Tue, 17 Nov 2026 16:02:37 +0100 Subject: [PATCH 6/8] docs(skip-ci): Link the changelog entry to its pull request --- CHANGELOG.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index d1bee4b..055e26e 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -4,7 +4,7 @@ ### Features -- Skip CI - Add an action that tells whether a push to a pull request only changes files that need no CI, such as Markdown, since a head whose run passed. Jobs gated on its `skip` output don't run for a CHANGELOG fix-up. +- Skip CI - Add an action that tells whether a push to a pull request only changes files that need no CI, such as Markdown, since a head whose run passed. Jobs gated on its `skip` output don't run for a CHANGELOG fix-up. ([#187](https://github.com/getsentry/github-workflows/pull/187)) ## 3.5.0 From 7d0131bb2d2b7d39cf823d6e6c4dc1d11bde6fcc Mon Sep 17 00:00:00 2001 From: bitsandfoxes Date: Tue, 17 Nov 2026 16:27:50 +0100 Subject: [PATCH 7/8] ci(skip-ci): Fail the test job when a Pester test fails --- .github/workflows/script-tests.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/script-tests.yml b/.github/workflows/script-tests.yml index cd04c76..3076ffb 100644 --- a/.github/workflows/script-tests.yml +++ b/.github/workflows/script-tests.yml @@ -34,7 +34,7 @@ jobs: steps: - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4 - - run: Invoke-Pester + - run: Invoke-Pester -CI working-directory: skip-ci shell: pwsh From e8f25dd65e06243d145a224daad5df6c7baa29d8 Mon Sep 17 00:00:00 2001 From: bitsandfoxes Date: Tue, 17 Nov 2026 22:15:19 +0100 Subject: [PATCH 8/8] fix(skip-ci): Ignore a leading slash in patterns --- skip-ci/README.md | 1 + skip-ci/scripts/match-paths.ps1 | 2 ++ skip-ci/tests/match-paths.Tests.ps1 | 7 +++++++ 3 files changed, 10 insertions(+) diff --git a/skip-ci/README.md b/skip-ci/README.md index 117ef77..e8754c2 100644 --- a/skip-ci/README.md +++ b/skip-ci/README.md @@ -73,6 +73,7 @@ When it skips, the action writes the reason to the job summary. - `*` matches any characters except `/`, so `*.md` matches only Markdown files at the root. - `?` matches one character except `/`. - A pattern starting with `!` takes matching files back out. The last pattern that matches a file decides, so `!package/**` after `**/*.md` keeps Markdown files under `package/` needing CI. +- A leading `/` is ignored, so `!/package/**` and `!package/**` are the same. - Blank lines and lines starting with `#` are ignored. Matching is case-sensitive. These are not GitHub's `paths` filter patterns: `?`, `+` and `[...]` mean something else there. diff --git a/skip-ci/scripts/match-paths.ps1 b/skip-ci/scripts/match-paths.ps1 index 53a6cbd..d452043 100644 --- a/skip-ci/scripts/match-paths.ps1 +++ b/skip-ci/scripts/match-paths.ps1 @@ -2,6 +2,7 @@ # A pattern starting with '!' takes matching files back out; the last pattern that matches a file decides. # '**' matches any characters including '/', and a leading '**/' also matches files at the root; # '*' matches any characters except '/'; '?' matches one character except '/'. Matching is case-sensitive. +# A leading '/' is ignored, since file names are relative to the repository root. param( [Parameter(Mandatory = $true)][AllowEmptyCollection()][string[]] $Files, [Parameter(Mandatory = $true)][AllowEmptyCollection()][AllowEmptyString()][string[]] $Patterns @@ -56,6 +57,7 @@ $rules = @(foreach ($pattern in $Patterns) { $pattern = $pattern.Substring(1) } + $pattern = $pattern.TrimStart('/') [pscustomobject]@{ Regex = ConvertTo-Regex $pattern; Exclude = $exclude } }) diff --git a/skip-ci/tests/match-paths.Tests.ps1 b/skip-ci/tests/match-paths.Tests.ps1 index fca8b93..064dfaa 100644 --- a/skip-ci/tests/match-paths.Tests.ps1 +++ b/skip-ci/tests/match-paths.Tests.ps1 @@ -45,6 +45,13 @@ Describe 'match-paths' { MatchPaths @('package-dev/Documentation~/index.md') $patterns | Should -BeFalse } + It 'ignores a leading slash' { + $patterns = @('**/*.md', '!/package/**') + MatchPaths @('README.md') $patterns | Should -BeTrue + MatchPaths @('package/README.md') $patterns | Should -BeFalse + MatchPaths @('README.md') @('/README.md') | Should -BeTrue + } + It 'the last matching pattern wins' { MatchPaths @('docs/keep.md') @('**/*.md', '!docs/**', 'docs/keep.md') | Should -BeTrue }