Skip to content

Commit 7beaee2

Browse files
matejchalkmatejchalk
committed
Create proper README
1 parent fcbbea1 commit 7beaee2

File tree

2 files changed

+61
-202
lines changed

2 files changed

+61
-202
lines changed

‎README.md

+61-202
Original file line numberDiff line numberDiff line change
@@ -1,229 +1,88 @@
1-
# Create a GitHub Action Using TypeScript
1+
# Code PushUp GitHub Action
22

33
[![GitHub Super-Linter](https://github.com/actions/typescript-action/actions/workflows/linter.yml/badge.svg)](https://github.com/super-linter/super-linter)
44
![CI](https://github.com/actions/typescript-action/actions/workflows/ci.yml/badge.svg)
55
[![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)
66
[![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)
77
[![Coverage](./badges/coverage.svg)](./badges/coverage.svg)
88

9-
Use this template to bootstrap the creation of a TypeScript action. :rocket:
9+
**🤖 GitHub Action for integrating
10+
[Code PushUp](https://github.com/code-pushup/cli/tree/main/packages/cli#readme)
11+
into your CI workflows.**
1012

11-
This template includes compilation support, tests, a validation workflow,
12-
publishing, and versioning guidance.
13+
![showcase](./images/showcase.png)
1314

14-
If you are new, there's also a simpler introduction in the
15-
[Hello world JavaScript action repository](https://github.com/actions/hello-world-javascript-action).
15+
## Features
1616

17-
## Create Your Own Action
17+
- 📃 Collects a Code PushUp report on push to remote branch.
18+
- 📉 Uploads reports to workflow artifacts and/or Code PushUp portal (optional).
19+
- 💬 When a PR is opened/updated, compares reports for source and target
20+
branches, and creates/updates a PR comment which summarizes the impact of the
21+
changes.
1822

19-
To create your own action, you can use this repository as a template! Just
20-
follow the below instructions:
23+
## Workflow example
2124

22-
1. Click the **Use this template** button at the top of the repository
23-
1. Select **Create a new repository**
24-
1. Select an owner and name for your new repository
25-
1. Click **Create repository**
26-
1. Clone your new repository
25+
```yml
26+
name: Code PushUp
2727

28-
> [!IMPORTANT]
29-
>
30-
> Make sure to remove or update the [`CODEOWNERS`](./CODEOWNERS) file! For
31-
> details on how to use this file, see
32-
> [About code owners](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-code-owners).
28+
on:
29+
push:
30+
branches: [main]
31+
pull_request:
32+
branches: [main]
3333

34-
## Initial Setup
34+
permissions:
35+
pull-requests: write
3536

36-
After you've cloned the repository to your local machine or codespace, you'll
37-
need to perform some initial setup steps before you can develop your action.
38-
39-
> [!NOTE]
40-
>
41-
> You'll need to have a reasonably modern version of
42-
> [Node.js](https://nodejs.org) handy (20.x or later should work!). If you are
43-
> using a version manager like [`nodenv`](https://github.com/nodenv/nodenv) or
44-
> [`nvm`](https://github.com/nvm-sh/nvm), this template has a `.node-version`
45-
> file at the root of the repository that will be used to automatically switch
46-
> to the correct version when you `cd` into the repository. Additionally, this
47-
> `.node-version` file is used by GitHub Actions in any `actions/setup-node`
48-
> actions.
49-
50-
1. :hammer_and_wrench: Install the dependencies
51-
52-
```bash
53-
npm install
54-
```
55-
56-
1. :building_construction: Package the TypeScript for distribution
57-
58-
```bash
59-
npm run bundle
60-
```
61-
62-
1. :white_check_mark: Run the tests
63-
64-
```bash
65-
$ npm test
66-
67-
PASS ./index.test.js
68-
✓ throws invalid number (3ms)
69-
✓ wait 500 ms (504ms)
70-
✓ test runs (95ms)
71-
72-
...
73-
```
74-
75-
## Update the Action Metadata
76-
77-
The [`action.yml`](action.yml) file defines metadata about your action, such as
78-
input(s) and output(s). For details about this file, see
79-
[Metadata syntax for GitHub Actions](https://docs.github.com/en/actions/creating-actions/metadata-syntax-for-github-actions).
80-
81-
When you copy this repository, update `action.yml` with the name, description,
82-
inputs, and outputs for your action.
83-
84-
## Update the Action Code
85-
86-
The [`src/`](./src/) directory is the heart of your action! This contains the
87-
source code that will be run when your action is invoked. You can replace the
88-
contents of this directory with your own code.
89-
90-
There are a few things to keep in mind when writing your action code:
91-
92-
- Most GitHub Actions toolkit and CI/CD operations are processed asynchronously.
93-
In `main.ts`, you will see that the action is run in an `async` function.
94-
95-
```javascript
96-
import * as core from '@actions/core'
97-
//...
98-
99-
async function run() {
100-
try {
101-
//...
102-
} catch (error) {
103-
core.setFailed(error.message)
104-
}
105-
}
106-
```
107-
108-
For more information about the GitHub Actions toolkit, see the
109-
[documentation](https://github.com/actions/toolkit/blob/master/README.md).
110-
111-
So, what are you waiting for? Go ahead and start customizing your action!
112-
113-
1. Create a new branch
114-
115-
```bash
116-
git checkout -b releases/v1
117-
```
118-
119-
1. Replace the contents of `src/` with your action code
120-
1. Add tests to `__tests__/` for your source code
121-
1. Format, test, and build the action
122-
123-
```bash
124-
npm run all
125-
```
126-
127-
> This step is important! It will run [`ncc`](https://github.com/vercel/ncc)
128-
> to build the final JavaScript action code with all dependencies included.
129-
> If you do not run this step, your action will not work correctly when it is
130-
> used in a workflow. This step also includes the `--license` option for
131-
> `ncc`, which will create a license file for all of the production node
132-
> modules used in your project.
133-
134-
1. Commit your changes
135-
136-
```bash
137-
git add .
138-
git commit -m "My first action is ready!"
139-
```
140-
141-
1. Push them to your repository
142-
143-
```bash
144-
git push -u origin releases/v1
145-
```
146-
147-
1. Create a pull request and get feedback on your action
148-
1. Merge the pull request into the `main` branch
149-
150-
Your action is now published! :rocket:
151-
152-
For information about versioning your action, see
153-
[Versioning](https://github.com/actions/toolkit/blob/master/docs/action-versioning.md)
154-
in the GitHub Actions toolkit.
37+
jobs:
38+
code-pushup:
39+
runs-on: ubuntu-latest
40+
steps:
41+
- uses: actions/checkout@v4
42+
- uses: actions/setup-node@v4
43+
- run: npm ci
44+
- uses: code-pushup/github-action@v0
45+
```
15546
156-
## Validate the Action
47+
## Action inputs
15748
158-
You can now validate the action by referencing it in a workflow file. For
159-
example, [`ci.yml`](./.github/workflows/ci.yml) demonstrates how to reference an
160-
action in the same repository.
49+
The action may be customized using the following optional inputs:
16150
162-
```yaml
163-
steps:
164-
- name: Checkout
165-
id: checkout
166-
uses: actions/checkout@v4
51+
| Name | Description | Default |
52+
| :---------- | :----------------------------------------------- | :----------------------------------------------------------------------------------------------------- |
53+
| `token` | GitHub token for authorizing GitHub API requests | `${{ github.token }}` |
54+
| `artifacts` | Toggles if artifacts will we uploaded/downloaded | `true` |
55+
| `retention` | Artifact retention period in days | from repository settings |
56+
| `directory` | Directory in which `code-pushup` should run | `process.cwd()` |
57+
| `config` | Path to config file (`--config` option) | see [`@code-pushup/cli` docs](https://github.com/code-pushup/cli/tree/main/packages/cli#configuration) |
58+
| `silent` | Toggles if logs from Code PushUp CLI are printed | `false` |
59+
| `bin` | Command for executing Code PushUp CLI | `npx --no-install code-pushup` |
16760

168-
- name: Test Local Action
169-
id: test-action
170-
uses: ./
171-
with:
172-
milliseconds: 1000
61+
For example, this will run `code-pushup` commands in a non-root folder and
62+
retain report artifacts for 30 days:
17363

174-
- name: Print Output
175-
id: output
176-
run: echo "${{ steps.test-action.outputs.time }}"
64+
```yml
65+
- uses: code-pushup/github-action@v0
66+
with:
67+
directory: website
68+
retention: 30
17769
```
17870

179-
For example workflow runs, check out the
180-
[Actions tab](https://github.com/actions/typescript-action/actions)! :rocket:
181-
182-
## Usage
71+
## Action outputs
18372

184-
After testing, you can create version tag(s) that developers can use to
185-
reference different stable versions of your action. For more information, see
186-
[Versioning](https://github.com/actions/toolkit/blob/master/docs/action-versioning.md)
187-
in the GitHub Actions toolkit.
73+
Some outputs are set in case you want to add further steps to your workflow.
18874

189-
To include the action in a workflow in another repository, you can use the
190-
`uses` syntax with the `@` symbol to reference a specific branch, tag, or commit
191-
hash.
75+
| Name | Description |
76+
| :------------ | :------------------------------- |
77+
| `artifact-id` | ID of uploaded report artifact |
78+
| `comment-id` | ID of created/updated PR comment |
19279

193-
```yaml
194-
steps:
195-
- name: Checkout
196-
id: checkout
197-
uses: actions/checkout@v4
80+
Example of using step outputs:
19881

199-
- name: Test Local Action
200-
id: test-action
201-
uses: actions/typescript-action@v1 # Commit with the `v1` tag
202-
with:
203-
milliseconds: 1000
204-
205-
- name: Print Output
206-
id: output
207-
run: echo "${{ steps.test-action.outputs.time }}"
82+
```yml
83+
- uses: code-pushup/github-action@v0
84+
id: code-pushup
85+
- run: |
86+
echo "Comment ID is ${{ steps.code-pushup.outputs.comment-id }}"
87+
echo "Artifact ID is ${{ steps.code-pushup.outputs.artifact-id }}"
20888
```
209-
210-
## Publishing a New Release
211-
212-
This project includes a helper script, [`script/release`](./script/release)
213-
designed to streamline the process of tagging and pushing new releases for
214-
GitHub Actions.
215-
216-
GitHub Actions allows users to select a specific version of the action to use,
217-
based on release tags. This script simplifies this process by performing the
218-
following steps:
219-
220-
1. **Retrieving the latest release tag:** The script starts by fetching the most
221-
recent release tag by looking at the local data available in your repository.
222-
1. **Prompting for a new release tag:** The user is then prompted to enter a new
223-
release tag. To assist with this, the script displays the latest release tag
224-
and provides a regular expression to validate the format of the new tag.
225-
1. **Tagging the new release:** Once a valid new tag is entered, the script tags
226-
the new release.
227-
1. **Pushing the new tag to the remote:** Finally, the script pushes the new tag
228-
to the remote repository. From here, you will need to create a new release in
229-
GitHub and users can easily reference the new tag in their workflows.

‎images/showcase.png

180 KB
Loading

0 commit comments

Comments
 (0)