88
99Use this template to bootstrap the creation of a TypeScript action. :rocket :
1010
11- This template includes compilation support, tests, a validation workflow, publishing, and versioning
12- guidance.
11+ This template includes compilation support, tests, a validation workflow,
12+ publishing, and versioning guidance.
1313
1414If you are new, there's also a simpler introduction in the
1515[ Hello world JavaScript action repository] ( https://github.com/actions/hello-world-javascript-action ) .
1616
1717## Create Your Own Action
1818
19- To create your own action, you can use this repository as a template! Just follow the below
20- instructions:
19+ To create your own action, you can use this repository as a template! Just
20+ follow the below instructions:
2121
22221 . Click the ** Use this template** button at the top of the repository
23231 . Select ** Create a new repository**
@@ -27,23 +27,25 @@ instructions:
2727
2828> [ !IMPORTANT]
2929>
30- > Make sure to remove or update the [ ` CODEOWNERS ` ] ( ./CODEOWNERS ) file! For details on how to use
31- > this file, see
30+ > Make sure to remove or update the [ ` CODEOWNERS ` ] ( ./CODEOWNERS ) file! For
31+ > details on how to use this file, see
3232> [ About code owners] ( https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-code-owners ) .
3333
3434## Initial Setup
3535
36- After you've cloned the repository to your local machine or codespace, you'll need to perform some
37- initial setup steps before you can develop your action.
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.
3838
3939> [ !NOTE]
4040>
41- > You'll need to have a reasonably modern version of [ Node.js] ( https://nodejs.org ) handy (20.x or
42- > later should work!). If you are using a version manager like
43- > [ ` nodenv ` ] ( https://github.com/nodenv/nodenv ) or [ ` nvm ` ] ( https://github.com/nvm-sh/nvm ) , this
44- > template has a ` .node-version ` file at the root of the repository that will be used to
45- > automatically switch to the correct version when you ` cd ` into the repository. Additionally, this
46- > ` .node-version ` file is used by GitHub Actions in any ` actions/setup-node ` actions.
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.
4749
48501 . :hammer_and_wrench : Install the dependencies
4951
@@ -72,23 +74,23 @@ initial setup steps before you can develop your action.
7274
7375## Update the Action Metadata
7476
75- The [ ` action.yml ` ] ( action.yml ) file defines metadata about your action, such as input(s) and
76- output(s). For details about this file, see
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
7779[ Metadata syntax for GitHub Actions] ( https://docs.github.com/en/actions/creating-actions/metadata-syntax-for-github-actions ) .
7880
79- When you copy this repository, update ` action.yml ` with the name, description, inputs, and outputs
80- for your action.
81+ When you copy this repository, update ` action.yml ` with the name, description,
82+ inputs, and outputs for your action.
8183
8284## Update the Action Code
8385
84- The [ ` src/ ` ] ( ./src/ ) directory is the heart of your action! This contains the source code that will
85- be run when your action is invoked. You can replace the contents of this directory with your own
86- code.
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.
8789
8890There are a few things to keep in mind when writing your action code:
8991
90- - Most GitHub Actions toolkit and CI/CD operations are processed asynchronously. In ` main.ts ` , you
91- will see that the action is run in an ` async ` function.
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.
9294
9395 ``` javascript
9496 import * as core from ' @actions/core'
@@ -122,11 +124,12 @@ So, what are you waiting for? Go ahead and start customizing your action!
122124 npm run all
123125 ```
124126
125- > This step is important! It will run [ ` ncc ` ] ( https://github.com/vercel/ncc ) to build the final
126- > JavaScript action code with all dependencies included. If you do not run this step, your action
127- > will not work correctly when it is used in a workflow. This step also includes the ` --license `
128- > option for ` ncc ` , which will create a license file for all of the production node modules used
129- > in your project.
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.
130133
1311341 . Commit your changes
132135
@@ -147,14 +150,14 @@ So, what are you waiting for? Go ahead and start customizing your action!
147150Your action is now published! :rocket :
148151
149152For information about versioning your action, see
150- [ Versioning] ( https://github.com/actions/toolkit/blob/master/docs/action-versioning.md ) in the GitHub
151- Actions toolkit.
153+ [ Versioning] ( https://github.com/actions/toolkit/blob/master/docs/action-versioning.md )
154+ in the GitHub Actions toolkit.
152155
153156## Validate the Action
154157
155- You can now validate the action by referencing it in a workflow file. For example,
156- [ ` ci.yml ` ] ( ./.github/workflows/ci.yml ) demonstrates how to reference an action in the same
157- repository.
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.
158161
159162``` yaml
160163steps :
@@ -178,13 +181,14 @@ For example workflow runs, check out the
178181
179182## Usage
180183
181- After testing, you can create version tag(s) that developers can use to reference different stable
182- versions of your action. For more information, see
183- [Versioning](https://github.com/actions/toolkit/blob/master/docs/action-versioning.md) in the GitHub
184- Actions toolkit.
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.
185188
186- To include the action in a workflow in another repository, you can use the ` uses` syntax with the
187- ` @` symbol to reference a specific branch, tag, or commit hash.
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.
188192
189193` ` ` yaml
190194steps:
@@ -205,22 +209,27 @@ steps:
205209
206210## Publishing a New Release
207211
208- This project includes a helper script, [` script/release`](./script/release) designed to streamline
209- the process of tagging and pushing new releases for GitHub Actions.
210-
211- GitHub Actions allows users to select a specific version of the action to use, based on release
212- tags. This script simplifies this process by performing the following steps :
213-
214- 1. **Retrieving the latest release tag:** The script starts by fetching the most recent SemVer
215- release tag of the current branch, by looking at the local data available in your repository.
216- 1. **Prompting for a new release tag:** The user is then prompted to enter a new release tag. To
217- assist with this, the script displays the tag retrieved in the previous step, and validates the
218- format of the inputted tag (vX.X.X). The user is also reminded to update the version field in
219- package.json.
220- 1. **Tagging the new release:** The script then tags a new release and syncs the separate major tag
221- (e.g. v1, v2) with the new release tag (e.g. v1.0.0, v2.1.2). When the user is creating a new
222- major release, the script auto-detects this and creates a `releases/v#` branch for the previous
223- major version.
224- 1. **Pushing changes to remote:** Finally, the script pushes the necessary commits, tags and
225- branches to the remote repository. From here, you will need to create a new release in GitHub so
226- users can easily reference the new tags in their workflows.
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 SemVer release tag of the current branch, by looking at the local data
222+ 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 tag retrieved in
225+ the previous step, and validates the format of the inputted tag (vX.X.X). The
226+ user is also reminded to update the version field in package.json.
227+ 1. **Tagging the new release:** The script then tags a new release and syncs the
228+ separate major tag (e.g. v1, v2) with the new release tag (e.g. v1.0.0,
229+ v2.1.2). When the user is creating a new major release, the script
230+ auto-detects this and creates a `releases/v#` branch for the previous major
231+ version.
232+ 1. **Pushing changes to remote:** Finally, the script pushes the necessary
233+ commits, tags and branches to the remote repository. From here, you will need
234+ to create a new release in GitHub so users can easily reference the new tags
235+ in their workflows.
0 commit comments