Skip to content

Commit 3d4fd8a

Browse files
SigureMoSigureMo
committed
📝 docs: write basic README for project
1 parent b3ed535 commit 3d4fd8a

File tree

2 files changed

+129
-232
lines changed

2 files changed

+129
-232
lines changed

‎README.md‎

Lines changed: 124 additions & 227 deletions
Original file line numberDiff line numberDiff line change
@@ -1,255 +1,152 @@
1-
# Create a GitHub Action Using TypeScript
1+
# CI Bypass
22

3-
![CI](https://github.com/actions/typescript-action/actions/workflows/ci.yml/badge.svg)
4-
[![Check dist/](https://github.com/actions/typescript-action/actions/workflows/check-dist.yml/badge.svg)](https://github.com/actions/typescript-action/actions/workflows/check-dist.yml)
5-
[![CodeQL](https://github.com/actions/typescript-action/actions/workflows/codeql-analysis.yml/badge.svg)](https://github.com/actions/typescript-action/actions/workflows/codeql-analysis.yml)
3+
Bypass CI checks for GitHub Actions.
64

7-
Use this template to bootstrap the creation of a TypeScript action. :rocket:
5+
This action allows some users have no maintainers permissions to bypass CI checks. It is useful for CI/CD team to bypass CI checks on some special cases.
86

9-
This template includes compilation support, tests, a validation workflow,
10-
publishing, and versioning guidance.
11-
12-
If you are new, there's also a simpler introduction in the
13-
[Hello world JavaScript action repository](https://github.com/actions/hello-world-javascript-action).
14-
15-
## Create Your Own Action
16-
17-
To create your own action, you can use this repository as a template! Just
18-
follow the below instructions:
19-
20-
1. Click the **Use this template** button at the top of the repository
21-
1. Select **Create a new repository**
22-
1. Select an owner and name for your new repository
23-
1. Click **Create repository**
24-
1. Clone your new repository
25-
26-
## Initial Setup
27-
28-
After you've cloned the repository to your local machine or codespace, you'll
29-
need to perform some initial setup steps before you can develop your action.
30-
31-
> [!NOTE]
32-
>
33-
> You'll need to have a reasonably modern version of
34-
> [Node.js](https://nodejs.org) handy (20.x or later should work!). If you are
35-
> using a version manager like [`nodenv`](https://github.com/nodenv/nodenv) or
36-
> [`fnm`](https://github.com/Schniz/fnm), this template has a `.node-version`
37-
> file at the root of the repository that can be used to automatically switch to
38-
> the correct version when you `cd` into the repository. Additionally, this
39-
> `.node-version` file is used by GitHub Actions in any `actions/setup-node`
40-
> actions.
41-
42-
1. :hammer_and_wrench: Install the dependencies
43-
44-
```bash
45-
npm install
46-
```
47-
48-
1. :building_construction: Package the TypeScript for distribution
49-
50-
```bash
51-
npm run bundle
52-
```
53-
54-
1. :white_check_mark: Run the tests
55-
56-
```bash
57-
$ npm test
58-
59-
PASS ./index.test.js
60-
✓ throws invalid number (3ms)
61-
✓ wait 500 ms (504ms)
62-
✓ test runs (95ms)
63-
64-
...
65-
```
66-
67-
## Update the Action Metadata
68-
69-
The [`action.yml`](action.yml) file defines metadata about your action, such as
70-
input(s) and output(s). For details about this file, see
71-
[Metadata syntax for GitHub Actions](https://docs.github.com/en/actions/creating-actions/metadata-syntax-for-github-actions).
7+
## Usage
728

73-
When you copy this repository, update `action.yml` with the name, description,
74-
inputs, and outputs for your action.
9+
### Skip job
7510

76-
## Update the Action Code
11+
```yaml
12+
jobs:
13+
check-bypass:
14+
name: Check Bypass
15+
runs-on: ubuntu-latest
16+
permissions:
17+
contents: read
18+
outputs:
19+
can-skip: ${{ steps.check-bypass.outputs.can-skip }}
20+
steps:
21+
- id: check-bypass
22+
name: Check Bypass
23+
uses: PFCCLab/ci-bypass@v1
24+
with:
25+
github-token: ${{ secrets.GITHUB_TOKEN }}
26+
non-pull-request-event-strategy: 'always-skipped'
27+
type: 'labeled'
28+
label: 'ci-bypass: example | ci-bypass: all'
29+
username: 'SigureMo'
30+
31+
build:
32+
needs: check-bypass
33+
if: ${{ needs.check-bypass.outputs.can-skip != 'true' }}
34+
name: Build
35+
runs-on: ubuntu-latest
36+
37+
steps:
38+
- name: Run build
39+
run: echo "Run build"
40+
```
7741
78-
The [`src/`](./src/) directory is the heart of your action! This contains the
79-
source code that will be run when your action is invoked. You can replace the
80-
contents of this directory with your own code.
42+
### Skip steps
8143
82-
There are a few things to keep in mind when writing your action code:
44+
```yaml
45+
permissions:
46+
contents: read
47+
jobs:
48+
build:
49+
name: Build
50+
runs-on: ubuntu-latest
51+
52+
steps:
53+
- id: check-bypass
54+
name: Check Bypass
55+
uses: PFCCLab/ci-bypass@v1
56+
with:
57+
github-token: ${{ secrets.GITHUB_TOKEN }}
58+
non-pull-request-event-strategy: 'always-skipped'
59+
type: 'labeled'
60+
label: 'ci-bypass: example | ci-bypass: all'
61+
username: 'SigureMo'
62+
- name: Run build
63+
if: ${{ steps.check-bypass.outputs.can-skip != 'true' }}
64+
run: echo "Run build"
65+
```
8366
84-
- Most GitHub Actions toolkit and CI/CD operations are processed asynchronously.
85-
In `main.ts`, you will see that the action is run in an `async` function.
67+
### Skip with composite rule
8668
87-
```javascript
88-
import * as core from '@actions/core'
89-
//...
69+
```yaml
70+
permissions:
71+
contents: read
72+
jobs:
73+
build:
74+
name: Build
75+
runs-on: ubuntu-latest
76+
77+
steps:
78+
- id: check-bypass
79+
name: Check Bypass
80+
uses: PFCCLab/ci-bypass@v1
81+
with:
82+
github-token: ${{ secrets.GITHUB_TOKEN }}
83+
non-pull-request-event-strategy: 'always-skipped'
84+
type: 'composite'
85+
composite-rule: |
86+
{
87+
"any": [
88+
{
89+
"type": "labeled",
90+
"label": ["ci-bypass: example", "ci-bypass: all"],
91+
"username": ["SigureMo"]
92+
},
93+
{
94+
"type": "commented",
95+
"comment-pattern": [".+/bypass example.+", ".+/bypass all.+"],
96+
"username": ["SigureMo"]
97+
},
98+
{
99+
"type": "approved",
100+
"username": ["SigureMo", "gouzil"]
101+
}
102+
]
103+
}
104+
- name: Run build
105+
if: ${{ steps.check-bypass.outputs.can-skip != 'true' }}
106+
run: echo "Run build"
107+
```
90108
91-
async function run() {
92-
try {
93-
//...
94-
} catch (error) {
95-
core.setFailed(error.message)
96-
}
97-
}
98-
```
109+
### All options
99110
100-
For more information about the GitHub Actions toolkit, see the
101-
[documentation](https://github.com/actions/toolkit/blob/master/README.md).
111+
<!-- prettier-ignore -->
112+
| Name | Description | Required | Default |
113+
| - | - | - | - |
114+
| `github-token` | GitHub token to access GitHub API | false | `undefined` |
115+
| `non-pull-request-event-strategy` | Strategy to apply to non-pull-request events, can be always-skipped, never-skipped, or always-failed, default is always-failed | true | `always-failed` |
116+
| `type` | Type of the rule, can be `labeled`, `commented`, `approved`, or `composite` | true | `labeled` |
117+
| `username` | Username, can be a string or an array of strings separated by `\|` | false | `undefined` |
118+
| `user-team` | User team, can be a string or an array of strings separated by `\|` | false | `undefined` |
119+
| `label` | Label name, can be a string or an array of strings separated by `\|` | false | `undefined` |
120+
| `comment-pattern` | Comment regex pattern, can be a string or an array of strings separated by `\|` | false | `undefined` |
121+
| `composite-rule` | Use any, all or not to combine multiple rules, need to be a JSON string | false | `undefined` |
102122

103-
So, what are you waiting for? Go ahead and start customizing your action!
123+
> [!NOTE]
124+
>
125+
> `user-team` needs `read:org` permission, but the default `GITHUB_TOKEN` doesn't have this permission. You need to create a personal token with `read:org` permission.
104126

105-
1. Create a new branch
127+
## Contributing
106128

107-
```bash
108-
git checkout -b releases/v1
109-
```
129+
### Initial setup
110130

111-
1. Replace the contents of `src/` with your action code
112-
1. Add tests to `__tests__/` for your source code
113-
1. Format, test, and build the action
131+
1. Install the dependencies:
114132

115133
```bash
116-
npm run all
134+
pnpm install
117135
```
118136

119-
> This step is important! It will run [`ncc`](https://github.com/vercel/ncc)
120-
> to build the final JavaScript action code with all dependencies included.
121-
> If you do not run this step, your action will not work correctly when it is
122-
> used in a workflow. This step also includes the `--license` option for
123-
> `ncc`, which will create a license file for all of the production node
124-
> modules used in your project.
125-
126-
1. (Optional) Test your action locally
127-
128-
The [`@github/local-action`](https://github.com/github/local-action) utility
129-
can be used to test your action locally. It is a simple command-line tool
130-
that "stubs" (or simulates) the GitHub Actions Toolkit. This way, you can run
131-
your TypeScript action locally without having to commit and push your changes
132-
to a repository.
133-
134-
The `local-action` utility can be run in the following ways:
135-
136-
- Visual Studio Code Debugger
137-
138-
Make sure to review and, if needed, update
139-
[`.vscode/launch.json`](./.vscode/launch.json)
140-
141-
- Terminal/Command Prompt
142-
143-
```bash
144-
# npx local action <action-yaml-path> <entrypoint> <dotenv-file>
145-
npx local-action . src/main.ts .env
146-
```
147-
148-
You can provide a `.env` file to the `local-action` CLI to set environment
149-
variables used by the GitHub Actions Toolkit. For example, setting inputs and
150-
event payload data used by your action. For more information, see the example
151-
file, [`.env.example`](./.env.example), and the
152-
[GitHub Actions Documentation](https://docs.github.com/en/actions/learn-github-actions/variables#default-environment-variables).
153-
154-
1. Commit your changes
137+
2. Test the basic functionality:
155138

156139
```bash
157-
git add .
158-
git commit -m "My first action is ready!"
140+
pnpm test
159141
```
160142

161-
1. Push them to your repository
143+
3. Run bundle:
162144

163145
```bash
164-
git push -u origin releases/v1
146+
pnpm bundle
165147
```
166148

167-
1. Create a pull request and get feedback on your action
168-
1. Merge the pull request into the `main` branch
169-
170-
Your action is now published! :rocket:
171-
172-
For information about versioning your action, see
173-
[Versioning](https://github.com/actions/toolkit/blob/master/docs/action-versioning.md)
174-
in the GitHub Actions toolkit.
175-
176-
## Validate the Action
177-
178-
You can now validate the action by referencing it in a workflow file. For
179-
example, [`ci.yml`](./.github/workflows/ci.yml) demonstrates how to reference an
180-
action in the same repository.
181-
182-
```yaml
183-
steps:
184-
- name: Checkout
185-
id: checkout
186-
uses: actions/checkout@v4
187-
188-
- name: Test Local Action
189-
id: test-action
190-
uses: ./
191-
with:
192-
milliseconds: 1000
193-
194-
- name: Print Output
195-
id: output
196-
run: echo "${{ steps.test-action.outputs.time }}"
197-
```
198-
199-
For example workflow runs, check out the
200-
[Actions tab](https://github.com/actions/typescript-action/actions)! :rocket:
201-
202-
## Usage
203-
204-
After testing, you can create version tag(s) that developers can use to
205-
reference different stable versions of your action. For more information, see
206-
[Versioning](https://github.com/actions/toolkit/blob/master/docs/action-versioning.md)
207-
in the GitHub Actions toolkit.
208-
209-
To include the action in a workflow in another repository, you can use the
210-
`uses` syntax with the `@` symbol to reference a specific branch, tag, or commit
211-
hash.
212-
213-
```yaml
214-
steps:
215-
- name: Checkout
216-
id: checkout
217-
uses: actions/checkout@v4
218-
219-
- name: Test Local Action
220-
id: test-action
221-
uses: actions/typescript-action@v1 # Commit with the `v1` tag
222-
with:
223-
milliseconds: 1000
224-
225-
- name: Print Output
226-
id: output
227-
run: echo "${{ steps.test-action.outputs.time }}"
228-
```
149+
## Acknowledgement
229150

230-
## Publishing a New Release
231-
232-
This project includes a helper script, [`script/release`](./script/release)
233-
designed to streamline the process of tagging and pushing new releases for
234-
GitHub Actions.
235-
236-
GitHub Actions allows users to select a specific version of the action to use,
237-
based on release tags. This script simplifies this process by performing the
238-
following steps:
239-
240-
1. **Retrieving the latest release tag:** The script starts by fetching the most
241-
recent SemVer release tag of the current branch, by looking at the local data
242-
available in your repository.
243-
1. **Prompting for a new release tag:** The user is then prompted to enter a new
244-
release tag. To assist with this, the script displays the tag retrieved in
245-
the previous step, and validates the format of the inputted tag (vX.X.X). The
246-
user is also reminded to update the version field in package.json.
247-
1. **Tagging the new release:** The script then tags a new release and syncs the
248-
separate major tag (e.g. v1, v2) with the new release tag (e.g. v1.0.0,
249-
v2.1.2). When the user is creating a new major release, the script
250-
auto-detects this and creates a `releases/v#` branch for the previous major
251-
version.
252-
1. **Pushing changes to remote:** Finally, the script pushes the necessary
253-
commits, tags and branches to the remote repository. From here, you will need
254-
to create a new release in GitHub so users can easily reference the new tags
255-
in their workflows.
151+
- [Legorooj/skip-ci](https://github.com/Legorooj/skip-ci) - Provide a way to skip CI checks in GitHub Actions.
152+
- [ast-grep/ast-grep](https://github.com/ast-grep/ast-grep) - Provide a interface to combine multiple rules.

0 commit comments

Comments
 (0)