-
Notifications
You must be signed in to change notification settings - Fork 0
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
- Loading branch information
Michal Dorner
committed
May 20, 2020
1 parent
4e726dd
commit f29479b
Showing
2 changed files
with
94 additions
and
92 deletions.
There are no files selected for viewing
This file contains 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 |
---|---|---|
@@ -1,101 +1,97 @@ | ||
<p align="center"> | ||
<a href="https://github.com/actions/typescript-action/actions"><img alt="typescript-action status" src="https://github.com/actions/typescript-action/workflows/build-test/badge.svg"></a> | ||
<a href="https://github.com/dorny/pr-changed-files-filter/actions"><img alt="typescript-action status" src="https://github.com/dorny/pr-changed-files-filter/workflows/build-test/badge.svg"></a> | ||
</p> | ||
|
||
# Create a JavaScript Action using TypeScript | ||
**CAUTION**: This action can be only used in a workflow triggered by `pull_request` event. | ||
|
||
Use this template to bootstrap the creation of a JavaScript action.:rocket: | ||
# Pull request changed files filter | ||
|
||
This template includes compilication support, tests, a validation workflow, publishing, and versioning guidance. | ||
This [Github Action](https://github.com/features/actions) enables conditional execution of workflow job steps considering which files are modified by a pull request. | ||
|
||
If you are new, there's also a simpler introduction. See the [Hello World JavaScript Action](https://github.com/actions/hello-world-javascript-action) | ||
It saves time and resources especially in monorepo setups, where you can run slow tasks (e.g. integration tests) only for changed components. | ||
Github workflows built-in | ||
[path filters](https://help.github.com/en/actions/referenceworkflow-syntax-for-github-actions#onpushpull_requestpaths) | ||
doesn't allow this because they doesn't work on a level of individual jobs or steps. | ||
|
||
## Create an action from this template | ||
## Usage | ||
|
||
Click the `Use this Template` and provide the new repo details for your action | ||
The action accepts filter rules in the YAML format. | ||
Each filter rule is a list of [glob expressions](https://github.com/isaacs/minimatch). | ||
Corresponding output variable will be created to indicate if there's a changed file matching any of the rule glob expressions. | ||
Output variables can be later used in the `if` clause to conditionally run specific steps. | ||
|
||
## Code in Master | ||
### Inputs | ||
- **`repo-token`**: GitHub Access Token - use `${{ github.token }}` | ||
- **`filters`**: YAML dictionary where keys specifies rule names and values are lists of path patterns | ||
|
||
Install the dependencies | ||
```bash | ||
$ npm install | ||
``` | ||
|
||
Build the typescript and package it for distribution | ||
```bash | ||
$ npm run build && npm run pack | ||
``` | ||
|
||
Run the tests :heavy_check_mark: | ||
```bash | ||
$ npm test | ||
|
||
PASS ./index.test.js | ||
✓ throws invalid number (3ms) | ||
✓ wait 500 ms (504ms) | ||
✓ test runs (95ms) | ||
|
||
... | ||
``` | ||
|
||
## Change action.yml | ||
|
||
The action.yml contains defines the inputs and output for your action. | ||
|
||
Update the action.yml with your name, description, inputs and outputs for your action. | ||
|
||
See the [documentation](https://help.github.com/en/articles/metadata-syntax-for-github-actions) | ||
|
||
## Change the Code | ||
|
||
Most toolkit and CI/CD operations involve async operations so the action is run in an async function. | ||
|
||
```javascript | ||
import * as core from '@actions/core'; | ||
... | ||
|
||
async function run() { | ||
try { | ||
... | ||
} | ||
catch (error) { | ||
core.setFailed(error.message); | ||
} | ||
} | ||
|
||
run() | ||
``` | ||
### Outputs | ||
- For each rule it sets output variable named by the rule to text: | ||
- `'true'` - if **any** of changed files matches any of rule patterns | ||
- `'false'` - if **none** of changed files matches any of rule patterns | ||
|
||
See the [toolkit documentation](https://github.com/actions/toolkit/blob/master/README.md#packages) for the various packages. | ||
|
||
## Publish to a distribution branch | ||
|
||
Actions are run from GitHub repos so we will checkin the packed dist folder. | ||
|
||
Then run [ncc](https://github.com/zeit/ncc) and push the results: | ||
```bash | ||
$ npm run pack | ||
$ git add dist | ||
$ git commit -a -m "prod dependencies" | ||
$ git push origin releases/v1 | ||
``` | ||
|
||
Your action is now published! :rocket: | ||
|
||
See the [versioning documentation](https://github.com/actions/toolkit/blob/master/docs/action-versioning.md) | ||
|
||
## Validate | ||
|
||
You can now validate the action by referencing `./` in a workflow in your repo (see [test.yml](.github/workflows/test.yml)]) | ||
|
||
### Sample workflow | ||
```yaml | ||
uses: ./ | ||
with: | ||
milliseconds: 1000 | ||
... | ||
name: Build verification | ||
|
||
on: | ||
pull_request: | ||
types: | ||
- opened | ||
- edited | ||
- synchronize | ||
branches: | ||
- master | ||
jobs: | ||
tests: | ||
runs-on: ubuntu-latest | ||
steps: | ||
- uses: actions/checkout@v2 | ||
- uses: dorny/pr-changed-files-filter@v1 | ||
id: filter | ||
with: | ||
github-token: ${{ github.token }} | ||
filters: | | ||
backend: | ||
- 'backend/**/*' | ||
frontend: | ||
- 'frontend/**/*' | ||
# run only if 'backend' files were changed | ||
- name: backend unit tests | ||
if: steps.filter.outputs.backend == 'true' | ||
run: ... | ||
|
||
# run only if 'frontend' files were changed | ||
- name: frontend unit tests | ||
if: steps.filter.outputs.frontend == 'true' | ||
run: ... | ||
|
||
# run if 'backend' or 'frontend' files were changed | ||
- name: e2e tests | ||
if: steps.filter.outputs.backend == 'true' || steps.filter.outputs.frontend == 'true' | ||
run: ... | ||
``` | ||
See the [actions tab](https://github.com/actions/javascript-action/actions) for runs of this action! :rocket: | ||
## Usage: | ||
After testing you can [create a v1 tag](https://github.com/actions/toolkit/blob/master/docs/action-versioning.md) to reference the stable and latest V1 action | ||
## How it works | ||
1. Required inputs are checked (`github-token` & `filters`) | ||
2. Provided access token is used to fetch list of changed files. | ||
3. For each filter rule it checks if there is any matching file | ||
4. Output variables are set | ||
|
||
## Difference from related projects: | ||
|
||
- [Has Changed Path](https://github.com/MarceloPrado/has-changed-path) | ||
- detects changes from previous commit | ||
- you have to configure `checkout` action to fetch some number of previous commits | ||
- `git diff` is used for change detection | ||
- outputs only single `true` / `false` value if any of provided paths contains changes | ||
- [Changed Files Exporter](https://github.com/futuratrepadeira/changed-files) | ||
- outputs lists with paths of created, updated and deleted files | ||
- output is not directly usable in the `if` clause | ||
- [Changed File Filter](https://github.com/tony84727/changed-file-filter) | ||
- allows change detection between any refs or commits | ||
- fetches whole history of your git repository | ||
- might have negative performance impact on big repositories (github by default fetches only single commit) |
This file contains 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 |
---|---|---|
@@ -1,10 +1,16 @@ | ||
name: 'Your name here' | ||
description: 'Provide a description here' | ||
author: 'Your name or organization here' | ||
name: 'Pull request changed files filter' | ||
description: 'Enables conditional execution of workflow job steps considering which files are modified by a pull request.' | ||
author: 'Michal Dorner <dorner.michal@gmail.com>' | ||
inputs: | ||
myInput: # change this | ||
description: 'input description here' | ||
default: 'default value if applicable' | ||
github-token: | ||
description: 'GitHub Access Token - use ${{ github.token }}' | ||
required: true | ||
filters: | ||
description: 'YAML dictionary where keys specifies rule names and values are lists of (globbing) file path patterns' | ||
required: true | ||
runs: | ||
using: 'node12' | ||
main: 'dist/index.js' | ||
branding: | ||
color: blue | ||
icon: filter |