You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
> An opinionated alternative template to [`actions/javascript-action`](https://github.com/actions/javascript-action) to bootstrap the creation of a JavaScript action. 🚀
Use this template to bootstrap the creation of a JavaScript action.:rocket:
8
+
Use this template to bootstrap the creation of a JavaScript action.:rocket: Alternative to [`actions/javascript-action`](https://github.com/actions/javascript-action).
8
9
9
-
This template includes tests, linting, a validation workflow, publishing, and versioning guidance.
10
+
This template includes [release automation](.github/workflows), [tests](tests), linting, publishing, starter docs, and versioning guidance.
10
11
11
-
If you are new, there's also a simpler introduction. See the [Hello World JavaScript Action](https://github.com/actions/hello-world-javascript-action)
12
-
13
-
## Create an action from this template
14
-
15
-
Click the `Use this Template` and provide the new repo details for your action
16
-
17
-
## Code in Main
12
+
## Usage
18
13
19
-
Install the dependencies
14
+
Reference the published major/minor/patch tag, e.g. `v1`:
20
15
21
-
```bash
22
-
npm install
16
+
```yaml
17
+
uses: github-developer/javascript-action@v1
18
+
with:
19
+
milliseconds: 1000
23
20
```
24
21
25
-
Run the tests :heavy_check_mark:
26
-
27
-
```bash
28
-
$ npm test
29
-
30
-
PASS ./index.test.js
31
-
✓ throws invalid number (3ms)
32
-
✓ wait 500 ms (504ms)
33
-
✓ test runs (95ms)
34
-
...
35
-
```
22
+
See the [actions tab](https://github.com/github-developer/javascript-action/actions) for runs of this action! :rocket:
36
23
37
-
## Change action.yml
24
+
## Update your action metadata in `action.yml`
38
25
39
-
The action.yml defines the inputs and output for your action.
26
+
[`action.yml`](action.yml) defines the inputs and output for your action.
40
27
41
28
Update the action.yml with your name, description, inputs and outputs for your action.
42
29
43
-
See the [documentation](https://help.github.com/en/articles/metadata-syntax-for-github-actions)
30
+
See the [documentation](https://docs.github.com/en/actions/creating-actions/metadata-syntax-for-github-actions).
44
31
45
-
## Change the Code
32
+
## Write your action code in `lib`
46
33
47
34
Most toolkit and CI/CD operations involve async operations so the action is run in an async function.
48
35
@@ -64,53 +51,42 @@ run()
64
51
65
52
See the [toolkit documentation](https://github.com/actions/toolkit/blob/master/README.md#packages) for the various packages.
66
53
67
-
## Package for distribution
54
+
## Test your action in `tests`
68
55
69
-
GitHub Actions will run the entry point from the action.yml. Packaging assembles the code into one file that can be checked in to Git, enabling fast and reliable execution and preventing the need to check in node_modules.
56
+
[Jest](https://jestjs.io/) and [Nock](https://github.com/nock/nock) are included as suggestions for test and mocking frameworks.
70
57
71
-
Actions are run from GitHub repos. Packaging the action will create a packaged action in the dist folder.
58
+
A sample [Unit Test workflow](.github/workflows/test.yml) is provided which runs on every pull request and push to the `main` branch.
72
59
73
-
Run prepare
60
+
## Automate releases with GitHub Actions
74
61
75
-
```bash
76
-
npm run prepare
77
-
```
62
+
The entrypoint to your action is defined by `runs.using` in `action.yml`.
78
63
79
-
Since the packaged index.js is run from the dist folder.
64
+
This project uses a `prepare` script leveraging `@vercel/ncc` to compile and package the code into one minified `dist/index.js` file, enabling fast and reliable execution and preventing the need to check in the whole dependency tree in `node_modules`.
80
65
81
-
```bash
82
-
git add dist
83
-
```
84
-
85
-
## Create a release branch
86
-
87
-
Users shouldn't consume the action from master since that would be latest code and actions can break compatibility between major versions.
66
+
Here, `dist` is intentionally _not_ committed to Git branches for three reasons:
67
+
1. Encourage users to reference your action using [semantically versioned](https://semver.org/) tags like `v1`, `v1.1.5`, etc. instead of branches ([docs](https://docs.github.com/en/actions/creating-actions/about-actions#using-tags-for-release-management)).
68
+
2. Avoid a security vulnerability attack vector by encouraging community contributions to source code only, ignoring proposed compiled release assets.
69
+
3. Let automation do the hard part 🤖.
88
70
89
-
Checkin to the v1 release branch
71
+
A sample [Publish workflow](.github/workflows/publish.yml) is provided which runs on a `release` event to compile and package source code into `dist`, and force push major and minor tag versions according to the semantic version of the release. You can kick off this workflow and publish to GitHub Marketplace simply by [using the GitHub UI](https://docs.github.com/en/actions/creating-actions/publishing-actions-in-github-marketplace#publishing-an-action) to create a new semantically versioned release like `v1.0.3`.
90
72
91
-
```bash
92
-
git checkout -b v1
93
-
git commit -a -m "v1 release"
94
-
```
73
+
## Commit to open source maintainership
95
74
96
-
```bash
97
-
git push origin v1
98
-
```
75
+
A healthy open source community starts with communication. Either in this repository or in your organization's `.github` repository, we recommend reviewing, editing, and adopting:
76
+
- `CODE_OF_CONDUCT.md`for how to engage in community
77
+
- `CONTRIBUTING.md`for how to contribute to this project
78
+
- `LICENSE.md`for how to legally use and contribute to the project
- [Issue and pull request templates](https://docs.github.com/en/github/building-a-strong-community/about-issue-and-pull-request-templates)
99
81
100
-
Note: We recommend using the `--license` option for ncc, which will create a license file for all of the production node modules used in your project.
82
+
Issues and pull requests from the open source community should be attended to in a prompt, friendly, and proactive manner. Two sample workflows, [stale](.github/workflows/stale.yml) and [labeler](.github/workflows/labeler.yml) are provided to help with two small repetitious tasks.
101
83
102
-
Your action is now published! :rocket:
84
+
See [Open Source Guides](https://opensource.guide/best-practices/) for more guidance on maintaining a strong community.
103
85
104
-
See the [versioning documentation](https://github.com/actions/toolkit/blob/master/docs/action-versioning.md)
86
+
## License
105
87
106
-
## Usage
88
+
[MIT](LICENSE.md)
107
89
108
-
You can now consume the action by referencing the v1 branch
109
-
110
-
```yaml
111
-
uses: actions/javascript-action@v1
112
-
with:
113
-
milliseconds: 1000
114
-
```
90
+
## Contributing
115
91
116
-
See the [actions tab](https://github.com/actions/javascript-action/actions) for runs of this action! :rocket:
92
+
Pull requests are welcome! See [CONTRIBUTING.md](CONTRIBUTING.md) for more.
0 commit comments