88
99Use this template to bootstrap the creation of a TypeScript action. :rocket :
1010
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
12+ 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
20- follow the below instructions:
19+ To create your own action, you can use this repository as a template! Just follow the below
20+ instructions:
2121
22221 . Click the ** Use this template** button at the top of the repository
23231 . Select ** Create a new repository**
@@ -27,25 +27,23 @@ follow the below instructions:
2727
2828> [ !IMPORTANT]
2929>
30- > Make sure to remove or update the [ ` CODEOWNERS ` ] ( ./CODEOWNERS ) file! For
31- > details on how to use this file, see
30+ > Make sure to remove or update the [ ` CODEOWNERS ` ] ( ./CODEOWNERS ) file! For details on how to use
31+ > 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
37- need to perform some initial setup steps before you can develop your action.
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.
3838
3939> [ !NOTE]
4040>
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.
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.
4947
50481 . :hammer_and_wrench : Install the dependencies
5149
@@ -74,23 +72,23 @@ need to perform some initial setup steps before you can develop your action.
7472
7573## Update the Action Metadata
7674
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
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
7977[ Metadata syntax for GitHub Actions] ( https://docs.github.com/en/actions/creating-actions/metadata-syntax-for-github-actions ) .
8078
81- When you copy this repository, update ` action.yml ` with the name, description,
82- inputs, and outputs for your action.
79+ When you copy this repository, update ` action.yml ` with the name, description, inputs, and outputs
80+ for your action.
8381
8482## Update the Action Code
8583
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.
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.
8987
9088There are a few things to keep in mind when writing your action code:
9189
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.
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.
9492
9593 ``` javascript
9694 import * as core from ' @actions/core'
@@ -124,12 +122,11 @@ So, what are you waiting for? Go ahead and start customizing your action!
124122 npm run all
125123 ```
126124
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.
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.
133130
1341311 . Commit your changes
135132
@@ -150,14 +147,14 @@ So, what are you waiting for? Go ahead and start customizing your action!
150147Your action is now published! :rocket :
151148
152149For 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.
150+ [ Versioning] ( https://github.com/actions/toolkit/blob/master/docs/action-versioning.md ) in the GitHub
151+ Actions toolkit.
155152
156153## Validate the Action
157154
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.
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.
161158
162159``` yaml
163160steps :
@@ -181,14 +178,13 @@ For example workflow runs, check out the
181178
182179## Usage
183180
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.
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.
188185
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.
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.
192188
193189` ` ` yaml
194190steps:
@@ -209,27 +205,22 @@ steps:
209205
210206## Publishing a New Release
211207
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.
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.
0 commit comments