|
1 |
| -# Create a GitHub Action Using TypeScript |
| 1 | +# Pattini |
2 | 2 |
|
3 |
| -[](https://github.com/super-linter/super-linter) |
4 |
| - |
5 |
| -[](https://github.com/actions/typescript-action/actions/workflows/check-dist.yml) |
6 |
| -[](https://github.com/actions/typescript-action/actions/workflows/codeql-analysis.yml) |
| 3 | +[](https://github.com/super-linter/super-linter) |
| 4 | + |
| 5 | +[](https://github.com/actions/pattini/actions/workflows/check-dist.yml) |
| 6 | +[](https://github.com/actions/pattini/actions/workflows/codeql-analysis.yml) |
7 | 7 | [](./badges/coverage.svg)
|
8 | 8 |
|
9 |
| -Use this template to bootstrap the creation of a TypeScript action. :rocket: |
| 9 | +GitHub Action to reward contributors of a given GitHub repository. |
10 | 10 |
|
11 |
| -This template includes compilation support, tests, a validation workflow, |
12 |
| -publishing, and versioning guidance. |
| 11 | +## Install |
13 | 12 |
|
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). |
16 |
| - |
17 |
| -## Create Your Own Action |
18 |
| - |
19 |
| -To create your own action, you can use this repository as a template! Just |
20 |
| -follow the below instructions: |
21 |
| - |
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 |
27 |
| - |
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). |
33 |
| -
|
34 |
| -## Initial Setup |
35 |
| - |
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 |
| - > [!WARNING] |
128 |
| - > |
129 |
| - > This step is important! It will run [`ncc`](https://github.com/vercel/ncc) |
130 |
| - > to build the final JavaScript action code with all dependencies included. |
131 |
| - > If you do not run this step, your action will not work correctly when it is |
132 |
| - > used in a workflow. This step also includes the `--license` option for |
133 |
| - > `ncc`, which will create a license file for all of the production node |
134 |
| - > modules used in your project. |
135 |
| -
|
136 |
| -1. Commit your changes |
137 |
| - |
138 |
| - ```bash |
139 |
| - git add . |
140 |
| - git commit -m "My first action is ready!" |
141 |
| - ``` |
142 |
| - |
143 |
| -1. Push them to your repository |
144 |
| - |
145 |
| - ```bash |
146 |
| - git push -u origin releases/v1 |
147 |
| - ``` |
148 |
| - |
149 |
| -1. Create a pull request and get feedback on your action |
150 |
| -1. Merge the pull request into the `main` branch |
151 |
| - |
152 |
| -Your action is now published! :rocket: |
153 |
| - |
154 |
| -For information about versioning your action, see |
155 |
| -[Versioning](https://github.com/actions/toolkit/blob/master/docs/action-versioning.md) |
156 |
| -in the GitHub Actions toolkit. |
157 |
| - |
158 |
| -## Validate the Action |
159 |
| - |
160 |
| -You can now validate the action by referencing it in a workflow file. For |
161 |
| -example, [`ci.yml`](./.github/workflows/ci.yml) demonstrates how to reference an |
162 |
| -action in the same repository. |
163 |
| - |
164 |
| -```yaml |
165 |
| -steps: |
166 |
| - - name: Checkout |
167 |
| - id: checkout |
168 |
| - uses: actions/checkout@v4 |
169 |
| - |
170 |
| - - name: Test Local Action |
171 |
| - id: test-action |
172 |
| - uses: ./ |
173 |
| - with: |
174 |
| - milliseconds: 1000 |
175 |
| - |
176 |
| - - name: Print Output |
177 |
| - id: output |
178 |
| - run: echo "${{ steps.test-action.outputs.time }}" |
| 13 | +```bash |
| 14 | +npm install |
179 | 15 | ```
|
180 | 16 |
|
181 |
| -For example workflow runs, check out the |
182 |
| -[Actions tab](https://github.com/actions/typescript-action/actions)! :rocket: |
183 |
| -
|
184 |
| -## Usage |
185 |
| -
|
186 |
| -After testing, you can create version tag(s) that developers can use to |
187 |
| -reference different stable versions of your action. For more information, see |
188 |
| -[Versioning](https://github.com/actions/toolkit/blob/master/docs/action-versioning.md) |
189 |
| -in the GitHub Actions toolkit. |
| 17 | +## Build |
190 | 18 |
|
191 |
| -To include the action in a workflow in another repository, you can use the |
192 |
| -`uses` syntax with the `@` symbol to reference a specific branch, tag, or commit |
193 |
| -hash. |
194 |
| - |
195 |
| -```yaml |
196 |
| -steps: |
197 |
| - - name: Checkout |
198 |
| - id: checkout |
199 |
| - uses: actions/checkout@v4 |
200 |
| -
|
201 |
| - - name: Test Local Action |
202 |
| - id: test-action |
203 |
| - uses: actions/typescript-action@v1 # Commit with the `v1` tag |
204 |
| - with: |
205 |
| - milliseconds: 1000 |
206 |
| - |
207 |
| - - name: Print Output |
208 |
| - id: output |
209 |
| - run: echo "${{ steps.test-action.outputs.time }}" |
| 19 | +```bash |
| 20 | +npm run bundle |
210 | 21 | ```
|
211 | 22 |
|
212 |
| -## Publishing a new release |
| 23 | +## Test |
213 | 24 |
|
214 |
| -This project includes a helper script designed to streamline the process of |
215 |
| -tagging and pushing new releases for GitHub Actions. |
216 |
| -
|
217 |
| -GitHub Actions allows users to select a specific version of the action to use, |
218 |
| -based on release tags. Our script simplifies this process by performing the |
219 |
| -following steps: |
220 |
| -
|
221 |
| -1. **Retrieving the latest release tag:** The script starts by fetching the most |
222 |
| - recent release tag by looking at the local data available in your repository. |
223 |
| -1. **Prompting for a new release tag:** The user is then prompted to enter a new |
224 |
| - release tag. To assist with this, the script displays the latest release tag |
225 |
| - and provides a regular expression to validate the format of the new tag. |
226 |
| -1. **Tagging the new release:** Once a valid new tag is entered, the script tags |
227 |
| - the new release. |
228 |
| -1. **Pushing the new tag to the remote:** Finally, the script pushes the new tag |
229 |
| - to the remote repository. From here, you will need to create a new release in |
230 |
| - GitHub and users can easily reference the new tag in their workflows. |
| 25 | +```bash |
| 26 | +npm test |
| 27 | +``` |
0 commit comments