8
8
9
9
Use this template to bootstrap the creation of a TypeScript action. :rocket :
10
10
11
- This template includes compilation support, tests, a validation workflow,
12
- publishing, and versioning guidance.
11
+ This template includes compilation support, tests, a validation workflow, publishing, and versioning guidance.
13
12
14
13
If you are new, there's also a simpler introduction in the
15
14
[ Hello world JavaScript action repository] ( https://github.com/actions/hello-world-javascript-action ) .
16
15
17
16
## Create Your Own Action
18
17
19
- To create your own action, you can use this repository as a template! Just
20
- follow the below instructions:
18
+ To create your own action, you can use this repository as a template! Just follow the below instructions:
21
19
22
20
1 . Click the ** Use this template** button at the top of the repository
23
21
1 . Select ** Create a new repository**
@@ -27,25 +25,21 @@ follow the below instructions:
27
25
28
26
> [ !IMPORTANT]
29
27
>
30
- > Make sure to remove or update the [ ` CODEOWNERS ` ] ( ./CODEOWNERS ) file! For
31
- > details on how to use this file, see
28
+ > Make sure to remove or update the [ ` CODEOWNERS ` ] ( ./CODEOWNERS ) file! For details on how to use this file, see
32
29
> [ About code owners] ( https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-code-owners ) .
33
30
34
31
## Initial Setup
35
32
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.
33
+ After you've cloned the repository to your local machine or codespace, you'll need to perform some initial setup steps
34
+ before you can develop your action.
38
35
39
36
> [ !NOTE]
40
37
>
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
- > [ ` fnm ` ] ( https://github.com/Schniz/fnm ) , this template has a ` .node-version `
45
- > file at the root of the repository that can be used to automatically switch to
46
- > 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.
38
+ > You'll need to have a reasonably modern version of [ Node.js] ( https://nodejs.org ) handy (20.x or later should work!).
39
+ > If you are using a version manager like [ ` nodenv ` ] ( https://github.com/nodenv/nodenv ) or
40
+ > [ ` fnm ` ] ( https://github.com/Schniz/fnm ) , this template has a ` .node-version ` file at the root of the repository that
41
+ > can be used to automatically switch to the correct version when you ` cd ` into the repository. Additionally, this
42
+ > ` .node-version ` file is used by GitHub Actions in any ` actions/setup-node ` actions.
49
43
50
44
1 . :hammer_and_wrench : Install the dependencies
51
45
@@ -74,23 +68,21 @@ need to perform some initial setup steps before you can develop your action.
74
68
75
69
## Update the Action Metadata
76
70
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
71
+ The [ ` action.yml ` ] ( action.yml ) file defines metadata about your action, such as input(s) and output(s). For details
72
+ about this file, see
79
73
[ Metadata syntax for GitHub Actions] ( https://docs.github.com/en/actions/creating-actions/metadata-syntax-for-github-actions ) .
80
74
81
- When you copy this repository, update ` action.yml ` with the name, description,
82
- inputs, and outputs for your action.
75
+ When you copy this repository, update ` action.yml ` with the name, description, inputs, and outputs for your action.
83
76
84
77
## Update the Action Code
85
78
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.
79
+ The [ ` src/ ` ] ( ./src/ ) directory is the heart of your action! This contains the source code that will be run when your
80
+ action is invoked. You can replace the contents of this directory with your own code.
89
81
90
82
There are a few things to keep in mind when writing your action code:
91
83
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.
84
+ - Most GitHub Actions toolkit and CI/CD operations are processed asynchronously. In ` main.ts ` , you will see that the
85
+ action is run in an ` async ` function.
94
86
95
87
``` javascript
96
88
import * as core from ' @actions/core'
@@ -124,25 +116,21 @@ So, what are you waiting for? Go ahead and start customizing your action!
124
116
npm run all
125
117
```
126
118
127
- > This step is important! It will run [ ` rollup ` ] ( https://rollupjs.org/ ) to
128
- > build the final JavaScript action code with all dependencies included. If
129
- > you do not run this step, your action will not work correctly when it is
130
- > used in a workflow.
119
+ > This step is important! It will run [ ` rollup ` ] ( https://rollupjs.org/ ) to build the final JavaScript action code
120
+ > with all dependencies included. If you do not run this step, your action will not work correctly when it is used in
121
+ > a workflow.
131
122
132
123
1 . (Optional) Test your action locally
133
124
134
- The [ ` @github/local-action ` ] ( https://github.com/github/local-action ) utility
135
- can be used to test your action locally. It is a simple command-line tool
136
- that "stubs" (or simulates) the GitHub Actions Toolkit. This way, you can run
137
- your TypeScript action locally without having to commit and push your changes
138
- to a repository.
125
+ The [ ` @github/local-action ` ] ( https://github.com/github/local-action ) utility can be used to test your action locally.
126
+ It is a simple command-line tool that "stubs" (or simulates) the GitHub Actions Toolkit. This way, you can run your
127
+ TypeScript action locally without having to commit and push your changes to a repository.
139
128
140
129
The ` local-action ` utility can be run in the following ways:
141
130
142
131
- Visual Studio Code Debugger
143
132
144
- Make sure to review and, if needed, update
145
- [ ` .vscode/launch.json ` ] ( ./.vscode/launch.json )
133
+ Make sure to review and, if needed, update [ ` .vscode/launch.json ` ] ( ./.vscode/launch.json )
146
134
147
135
- Terminal/Command Prompt
148
136
@@ -151,10 +139,9 @@ So, what are you waiting for? Go ahead and start customizing your action!
151
139
npx @github/local-action . src/main.ts .env
152
140
```
153
141
154
- You can provide a ` .env` file to the ` local-action` CLI to set environment
155
- variables used by the GitHub Actions Toolkit. For example, setting inputs and
156
- event payload data used by your action. For more information, see the example
157
- file, [` .env.example` ](./.env.example), and the
142
+ You can provide a ` .env` file to the ` local-action` CLI to set environment variables used by the GitHub Actions
143
+ Toolkit. For example, setting inputs and event payload data used by your action. For more information, see the
144
+ example file, [` .env.example` ](./.env.example), and the
158
145
[GitHub Actions Documentation](https://docs.github.com/en/actions/learn-github-actions/variables#default-environment-variables).
159
146
160
147
1. Commit your changes
@@ -176,14 +163,12 @@ So, what are you waiting for? Go ahead and start customizing your action!
176
163
Your action is now published! :rocket:
177
164
178
165
For information about versioning your action, see
179
- [Versioning](https://github.com/actions/toolkit/blob/master/docs/action-versioning.md)
180
- in the GitHub Actions toolkit.
166
+ [Versioning](https://github.com/actions/toolkit/blob/master/docs/action-versioning.md) in the GitHub Actions toolkit.
181
167
182
168
# # Validate the Action
183
169
184
- You can now validate the action by referencing it in a workflow file. For
185
- example, [` ci.yml` ](./.github/workflows/ci.yml) demonstrates how to reference an
186
- action in the same repository.
170
+ You can now validate the action by referencing it in a workflow file. For example,
171
+ [` ci.yml` ](./.github/workflows/ci.yml) demonstrates how to reference an action in the same repository.
187
172
188
173
` ` ` yaml
189
174
steps:
@@ -202,19 +187,16 @@ steps:
202
187
run: echo " ${{ steps.test-action.outputs.time } }"
203
188
` ` `
204
189
205
- For example workflow runs, check out the
206
- [Actions tab](https://github.com/actions/typescript-action/actions)! :rocket:
190
+ For example workflow runs, check out the [Actions tab](https://github.com/actions/typescript-action/actions)! :rocket:
207
191
208
192
# # Usage
209
193
210
- After testing, you can create version tag(s) that developers can use to
211
- reference different stable versions of your action. For more information, see
212
- [Versioning](https://github.com/actions/toolkit/blob/master/docs/action-versioning.md)
194
+ After testing, you can create version tag(s) that developers can use to reference different stable versions of your
195
+ action. For more information, see [Versioning](https://github.com/actions/toolkit/blob/master/docs/action-versioning.md)
213
196
in the GitHub Actions toolkit.
214
197
215
- To include the action in a workflow in another repository, you can use the
216
- ` uses` syntax with the ` @` symbol to reference a specific branch, tag, or commit
217
- hash.
198
+ To include the action in a workflow in another repository, you can use the ` uses` syntax with the ` @` symbol to
199
+ reference a specific branch, tag, or commit hash.
218
200
219
201
` ` ` yaml
220
202
steps:
@@ -235,38 +217,29 @@ steps:
235
217
236
218
# # Publishing a New Release
237
219
238
- This project includes a helper script, [` script/release` ](./script/release)
239
- designed to streamline the process of tagging and pushing new releases for
240
- GitHub Actions.
220
+ This project includes a helper script, [` script/release` ](./script/release) designed to streamline the process of
221
+ tagging and pushing new releases for GitHub Actions.
241
222
242
- GitHub Actions allows users to select a specific version of the action to use,
243
- based on release tags. This script simplifies this process by performing the
244
- following steps:
223
+ GitHub Actions allows users to select a specific version of the action to use, based on release tags. This script
224
+ simplifies this process by performing the following steps:
245
225
246
- 1. ** Retrieving the latest release tag:** The script starts by fetching the most
247
- recent SemVer release tag of the current branch, by looking at the local data
248
- available in your repository.
249
- 1. ** Prompting for a new release tag:** The user is then prompted to enter a new
250
- release tag. To assist with this, the script displays the tag retrieved in
251
- the previous step, and validates the format of the inputted tag (vX.X.X). The
226
+ 1. ** Retrieving the latest release tag:** The script starts by fetching the most recent SemVer release tag of the
227
+ current branch, by looking at the local data available in your repository.
228
+ 1. ** Prompting for a new release tag:** The user is then prompted to enter a new release tag. To assist with this, the
229
+ script displays the tag retrieved in the previous step, and validates the format of the inputted tag (vX.X.X). The
252
230
user is also reminded to update the version field in package.json.
253
- 1. ** Tagging the new release:** The script then tags a new release and syncs the
254
- separate major tag (e.g. v1, v2) with the new release tag (e.g. v1.0.0,
255
- v2.1.2). When the user is creating a new major release, the script
256
- auto-detects this and creates a ` releases/v#` branch for the previous major
257
- version.
258
- 1. ** Pushing changes to remote:** Finally, the script pushes the necessary
259
- commits, tags and branches to the remote repository. From here, you will need
260
- to create a new release in GitHub so users can easily reference the new tags
261
- in their workflows.
231
+ 1. ** Tagging the new release:** The script then tags a new release and syncs the separate major tag (e.g. v1, v2) with
232
+ the new release tag (e.g. v1.0.0, v2.1.2). When the user is creating a new major release, the script auto-detects
233
+ this and creates a ` releases/v#` branch for the previous major version.
234
+ 1. ** Pushing changes to remote:** Finally, the script pushes the necessary commits, tags and branches to the remote
235
+ repository. From here, you will need to create a new release in GitHub so users can easily reference the new tags in
236
+ their workflows.
262
237
263
238
# # Dependency License Management
264
239
265
- This template includes a GitHub Actions workflow,
266
- [` licensed.yml` ](./.github/workflows/licensed.yml), that uses
267
- [Licensed](https://github.com/licensee/licensed) to check for dependencies with
268
- missing or non-compliant licenses. This workflow is initially disabled. To
269
- enable the workflow, follow the below steps.
240
+ This template includes a GitHub Actions workflow, [` licensed.yml` ](./.github/workflows/licensed.yml), that uses
241
+ [Licensed](https://github.com/licensee/licensed) to check for dependencies with missing or non-compliant licenses. This
242
+ workflow is initially disabled. To enable the workflow, follow the below steps.
270
243
271
244
1. Open [` licensed.yml` ](./.github/workflows/licensed.yml)
272
245
1. Uncomment the following lines:
@@ -282,16 +255,14 @@ enable the workflow, follow the below steps.
282
255
283
256
1. Save and commit the changes
284
257
285
- Once complete, this workflow will run any time a pull request is created or
286
- changes pushed directly to ` main` . If the workflow detects any dependencies with
287
- missing or non-compliant licenses, it will fail the workflow and provide details
258
+ Once complete, this workflow will run any time a pull request is created or changes pushed directly to ` main` . If the
259
+ workflow detects any dependencies with missing or non-compliant licenses, it will fail the workflow and provide details
288
260
on the issue(s) found.
289
261
290
262
# ## Updating Licenses
291
263
292
- Whenever you install or update dependencies, you can use the Licensed CLI to
293
- update the licenses database. To install Licensed, see the project' s
294
- [Readme](https://github.com/licensee/licensed?tab=readme-ov-file#installation).
264
+ Whenever you install or update dependencies, you can use the Licensed CLI to update the licenses database. To install
265
+ Licensed, see the project' s [Readme](https://github.com/licensee/licensed?tab=readme-ov-file#installation).
295
266
296
267
To update the cached licenses, run the following command:
297
268
0 commit comments