Repository navigation
feat(skip-ci): Add an action that skips CI for pushes changing only matching files #187
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Open
bitsandfoxes
wants to merge
8
commits into
main
Choose a base branch
from
spire/skip-ci-action
base: main
Could not load branches
Branch not found: {{ refName }}
Loading
Could not load tags
Nothing to show
Loading
Are you sure you want to change the base?
Some commits from the old base branch may be removed from the timeline,
and old review comments may become outdated.
Open
Changes from all commits
Commits
Show all changes
8 commits
Select commit
Hold shift + click to select a range
52fe3dc
feat(skip-ci): Add an action that skips CI for pushes changing only m…
bitsandfoxes b98144a
fix(skip-ci): Match the passing run to the pull request and use Peste…
bitsandfoxes 387b2d2
docs(skip-ci): Say which runs count for a pull request
bitsandfoxes 0fe277d
docs(skip-ci): Say the action needs gh and pwsh on the runner
bitsandfoxes 61b885a
docs(skip-ci): Say the jobs that need a failed check don't run
bitsandfoxes 4c355f5
docs(skip-ci): Link the changelog entry to its pull request
bitsandfoxes 7d0131b
ci(skip-ci): Fail the test job when a Pester test fails
bitsandfoxes e8f25dd
fix(skip-ci): Ignore a leading slash in patterns
bitsandfoxes File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,83 @@ | ||
| # 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@<sha> | ||
| 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. 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 | ||
|
|
||
| | 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, 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. | ||
|
|
||
| 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. | ||
|
|
||
| ## 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. | ||
| - 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. | ||
|
|
||
| ## 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. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,38 @@ | ||
| 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 }} | ||
| 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 }} | ||
| run: ${{ github.action_path }}/scripts/skip-ci.ps1 |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,84 @@ | ||
| # 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. | ||
| # 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 | ||
| ) | ||
|
|
||
| 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) | ||
| } | ||
| $pattern = $pattern.TrimStart('/') | ||
| [pscustomobject]@{ Regex = ConvertTo-Regex $pattern; Exclude = $exclude } | ||
|
bitsandfoxes marked this conversation as resolved.
Resolved
|
||
| }) | ||
|
|
||
| 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 | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,96 @@ | ||
| # 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 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. | ||
|
|
||
| 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" | ||
| # 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) | ||
| }) | ||
| 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 |
Oops, something went wrong.
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Uh oh!
There was an error while loading. Please reload this page.