Skip to content
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.

Sign up for GitHub

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

Jump to bottom

Enhance README #184

Merged
merged 2 commits into from
Jan 21, 2022
Merged

Enhance README #184

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
b534234
Enhance README
paescuj Jan 20, 2022
eb2b962
Merge branch 'master' into enhance-readme
fkirc Jan 21, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
154 changes: 94 additions & 60 deletions README.md
View file
Open in desktop
Expand Up @@ -47,7 +47,7 @@ However, GitHub's `paths-ignore` has some limitations:
To overcome those limitations, `skip-duplicate-actions` provides a more flexible `paths_ignore`-feature with an efficient backtracking-algorithm.
Instead of stupidly looking at the current commit, `paths_ignore` will look for successful checks in your commit-history.

You can use the [`paths_filter` option](#paths_filter) if you need to define multiple `paths_ignore` patterns in a single workflow.
You can use the [`paths_filter`](#paths_filter) option if you need to define multiple `paths_ignore` patterns in a single workflow.

## Skip if paths not changed

Expand All @@ -61,7 +61,7 @@ However, GitHub's `paths` has some limitations:
To overcome those limitations, `skip-duplicate-actions` provides a more sophisticated `paths`-feature.
Instead of blindly skipping checks, the backtracking-algorithm will only skip something if it can find a suitable check in your commit-history.

You can use the [`paths_filter` option](#paths_filter) if you need to define multiple `paths` patterns in a single workflow.
You can use the [`paths_filter`](#paths_filter) option if you need to define multiple `paths` patterns in a single workflow.

## Cancel outdated workflow-runs

Expand All @@ -75,22 +75,29 @@ Therefore, when you push changes to a branch, `skip-duplicate-actions` can be co

### `paths_ignore`

A JSON-array with ignored path patterns, e.g. something like `["**/README.md", "**/docs/**"]`.
A JSON-array with ignored path patterns.
See [cheat sheet](https://docs.github.com/en/actions/reference/workflow-syntax-for-github-actions#filter-pattern-cheat-sheet) for path-pattern examples.
See [micromatch](https://github.com/micromatch/micromatch) for details about supported path-patterns.
Default `[]`.

**Example:** `["**/README.md", "**/docs/**"]`

**Default:** `[]`

### `paths`

A JSON-array with path patterns, e.g. something like `["platform-specific/**"]`.
A JSON-array with path patterns.
If this is non-empty, then `skip-duplicate-actions` will try to skip commits that did not change any of those paths.
It uses the same syntax as `paths_ignore`.
Default `[]`.
It uses the same syntax as [`paths_ignore`](#paths_ignore).

**Example:** `["platform-specific/**"]`

**Default:** `[]`

### `paths_filter`

A YAML-string with named paths_ignore/paths patterns, e.g. something like:
A YAML-string with named [`paths_ignore`](#paths_ignore) / [`paths`](#paths) patterns.

**Example:**
```yaml
frontend:
paths_ignore:
Expand All @@ -100,80 +107,111 @@ frontend:
backend:
paths:
- 'backend/**/*'
### Here you can optionally control/limit backtracking
# Boolean or number (default: true)
# 'false' means disable backtracking completely
# '5' means to stop after having traced back 5 commits
backtracking: 5
```

Useful if you have multiple jobs in a workflow and want to skip them based on different `paths_ignore` / `paths` patterns.
See the corresponding [`paths_result` output](#paths_result-object) and [example configuration](#example-3-skip-using-paths_filter).
Useful if you have multiple jobs in a workflow and want to skip them based on different [`paths_ignore`](#paths_ignore) / [`paths`](#paths) patterns.
See the corresponding [`paths_result`](#paths_result) output and [example configuration](#example-3-skip-using-paths_filter).

### `cancel_others`

If true, then workflow-runs from outdated commits will be cancelled. Default `false`.
If true, then workflow-runs from outdated commits will be cancelled.

**Default:** `false`

### `skip_after_successful_duplicate`

If true, skip if an already finished duplicate run can be found. Default `true`.
If true, skip if an already finished duplicate run can be found.

**Default:** `true`

### `do_not_skip`

A JSON-array with triggers that should never be skipped. Default `["workflow_dispatch", "schedule"]`.
A JSON-array with triggers that should never be skipped.

**Default:** `["workflow_dispatch", "schedule"]`

### `concurrent_skipping`

One of `never`, `same_content`, `same_content_newer`, `outdated_runs`, `always`. Default `never`.
One of `never`, `same_content`, `same_content_newer`, `outdated_runs`, `always`.

**Default:** `never`

## Outputs

### `should_skip` (string)
### `should_skip`

Returns true if the current run should be skipped according to your configured rules. This should be evaluated for either individual steps or entire jobs.
Returns `true` if the current run should be skipped according to your configured rules. This should be evaluated for either individual steps or entire jobs.

### `reason` (string)
### `reason`

The reason why the current run is considered skippable or unskippable. Corresponds approximately to the input options.

- Example: `skip_after_successful_duplicate`

### `skipped_by` (object)

Returns information about the workflow run which caused the current run to be skipped. Returns information only when current run is considered skippable.
**Example:** `skip_after_successful_duplicate`

### `skipped_by`

Returns information about the workflow run which caused the current run to be skipped.

**Example:**
```jsonc
{
"event": "pull_request",
"treeHash": "e3434bb7aeb3047d7df948f09419ac96cf03d73e",
"commitHash": "4a0432e823468ecff81a978165cb35586544c795",
"status": "completed",
"conclusion": "success",
"html_url": "https://github.com/fkirc/skip-duplicate-actions/actions/runs/1709469369",
"branch": "master",
"repo": "fkirc/skip-duplicate-actions",
"runId": 1709469369,
"workflowId": 2640563,
"createdAt": "2022-01-17T18:56:06Z",
"runNumber": 737
}
```
- Returns information only when current run is considered skippable, otherwise an empty object (`{}`) is returned.

### `paths_result` (object)
### `paths_result`

Returns information for each configured filter in `paths_filter`.

- Example:
```json
{
"frontend": {
"should_skip": true,
"backtrack_count": 1,
"skipped_by": {
// Information about the workflow run
}
},
"backend": {
"should_skip": false,
"backtrack_count": 1,
"matched_files": ["backend/file.txt"]
},
"global": {
"should_skip": false,
"backtrack_count": 0
}
**Example:**
```jsonc
{
"frontend": {
"should_skip": true,
"backtrack_count": 1,
"skipped_by": { // Information about the workflow run },
"backend": {
"should_skip": false,
"backtrack_count": 1,
"matched_files": ["backend/file.txt"]
},
"global": {
"should_skip": false,
"backtrack_count": 0
}
```
- The `global` key corresponds to the "global" `paths_ignore` and `paths` inputs, which makes it possible to profit from the information of paths_result even when only defining "global" `paths_ignore` and/or `paths` inputs.
}
```
- The `global` key corresponds to the "global" [`paths_ignore`](#paths_ignore) and [`paths`](#paths) options.
- A list of matched files is returned in `matched_files`, if there are any.
- The `skipped_by` the return value behaves the same as the "global" [`skipped_by` output](#skipped_by-object).
- The `backtrack_count` shows how many commits where traced back (skipped) until a result has been found.
- If `skip-duplicate-actions` terminates before the paths checks are performed (for example, when a successful duplicate run has been found) `paths_result` returns an empty object (`{}`).
- The `skipped_by` return value behaves the same as the "global" [`skipped_by`](#skipped_by) output.
- The `backtrack_count` shows how many commits where traced back (skipped) until an appropriate commit has been found.
- If `skip-duplicate-actions` terminates before the paths checks are performed (for example, when a successful duplicate run has been found) an empty object is returned (`{}`).

### `changed_files` (array)
### `changed_files`

A two-dimensional array, with a list of changed files for each commit that has been traced back. Returns information only if one of the options `paths_ignore`, `paths` or `paths_filter` is set.
A two-dimensional array, with a list of changed files for each commit that has been traced back.

- Example: `[["some/example/file.txt", "another/example/file.txt"], ["frontend/file.txt"]]`
- Having a two-dimensional list makes processing flexible. For example, one can flatten (and uniquify) the list to get all changed files for all commits which were traced back. Or one can use `changed_files[0]` to get the changed files in the current commit. One might also use the output of `backtrack_count` from `paths_result` to process the list of changed files.
**Example:** `[["some/example/file.txt", "another/example/file.txt"], ["frontend/file.txt"]]`
- Having a two-dimensional list makes processing flexible. For example, one can flatten (and uniquify) the list to get changed files from all commits which were traced back. Or one can use `changed_files[0]` to get changed files from the latest commit. One might also use the output of `backtrack_count` from [`paths_result`](#paths_result) to process the list of changed files.
- Returns information only if one of the options [`paths_ignore`](#paths_ignore), [`paths`](#paths), [`paths_filter`](#paths_filter) is set.
- If `skip-duplicate-actions` terminates before the paths checks are performed (for example, when a successful duplicate run has been found) an empty array (`[]`) is returned.

## Usage examples

Expand Down Expand Up @@ -236,7 +274,7 @@ jobs:

### Example 3: Skip using `paths_filter`

The `paths_filter` option can be used if you have multiple jobs in a workflow and want to skip them based on different `paths_ignore` / `paths` patterns. When defining such filters, the action returns corresponding information in the `paths_result` output.
The `paths_filter` option can be used if you have multiple jobs in a workflow and want to skip them based on different [`paths_ignore`](#paths_ignore) / [`paths`](#paths) patterns. When defining such filters, the action returns corresponding information in the [`paths_result`](#paths_result) output.
For example in a monorepo, you might want to run jobs related to the "frontend" only if some files in the corresponding "frontend/" folder have changed and the same for "backend". This can be achieved with the following configuration:

```yml
Expand All @@ -259,18 +297,14 @@ jobs:
backend:
paths:
- 'backend/**/*'
### You can also control the backtracking behavior
# Can be a boolean or number (default: true)
# 5 means to stop after having traced back 5 commits
# backtracking: 5
# Can be mixed with the "global" paths_ignore/paths options, e.g.
# Can be mixed with the "global" 'paths_ignore' / 'paths' options, for example:
# paths_ignore: '["**/README.md"]'

frontend:
needs: pre_job
# If 'skip-duplicate-actions' terminates before the paths checks are performed (e.g., when a successful duplicate run has
# been found) paths_result output returns an empty object ({}). This can be easily intercepted in the if condition of a job
# by checking the result of the "global" should_skip output first.
# If 'skip-duplicate-actions' terminates before the paths checks are performed (for example, when a successful duplicate run has
# been found) 'paths_result' outputs an empty object ('{}'). This can be easily intercepted in the if condition of a job
# by checking the result of the "global" 'should_skip' output first.
if: needs.pre_job.outputs.should_skip != 'true' || !fromJSON(needs.pre_job.outputs.paths_result).frontend.should_skip
...

Expand Down