Add README info
This commit is contained in:
Nick Alteen
parent
36a902841b
commit
570107f4a0
3
LICENSE
3
LICENSE
|
|
@ -1,4 +1,5 @@
|
|||
MIT License
|
||||
|
||||
The MIT License (MIT)
|
||||
|
||||
Copyright (c) 2019 GitHub Actions
|
||||
|
||||
|
|
|
|||
229
README.md
229
README.md
|
|
@ -1,116 +1,199 @@
|
|||
# Create a JavaScript Action
|
||||
|
||||
<p align="center">
|
||||
<a href="https://github.com/actions/javascript-action/actions"><img alt="javscript-action status" src="https://github.com/actions/javascript-action/workflows/units-test/badge.svg"></a>
|
||||
</p>
|
||||
[](https://github.com/super-linter/super-linter)
|
||||
|
||||
|
||||
Use this template to bootstrap the creation of a JavaScript action.:rocket:
|
||||
Use this template to bootstrap the creation of a JavaScript action. :rocket:
|
||||
|
||||
This template includes tests, linting, a validation workflow, publishing, and versioning guidance.
|
||||
This template includes compilation support, tests, a validation workflow,
|
||||
publishing, and versioning guidance.
|
||||
|
||||
If you are new, there's also a simpler introduction. See the [Hello World JavaScript Action](https://github.com/actions/hello-world-javascript-action)
|
||||
If you are new, there's also a simpler introduction in the
|
||||
[Hello world JavaScript action repository](https://github.com/actions/hello-world-javascript-action).
|
||||
|
||||
## Create an action from this template
|
||||
## Create Your Own Action
|
||||
|
||||
Click the `Use this Template` and provide the new repo details for your action
|
||||
To create your own action, you can use this repository as a template! Just
|
||||
follow the below instructions:
|
||||
|
||||
## Code in Main
|
||||
1. Click the **Use this template** button at the top of the repository
|
||||
1. Select **Create a new repository**
|
||||
1. Select an owner and name for your new repository
|
||||
1. Click **Create repository**
|
||||
1. Clone your new repository
|
||||
|
||||
Install the dependencies
|
||||
## Initial Setup
|
||||
|
||||
```bash
|
||||
npm install
|
||||
```
|
||||
After you've cloned the repository to your local machine or codespace, you'll
|
||||
need to perform some initial setup steps before you can develop your action.
|
||||
|
||||
Run the tests :heavy_check_mark:
|
||||
> [!NOTE]
|
||||
>
|
||||
> You'll need to have a reasonably modern version of
|
||||
> [Node.js](https://nodejs.org) handy. If you are using a version manager like
|
||||
> [`nodenv`](https://github.com/nodenv/nodenv) or
|
||||
> [`nvm`](https://github.com/nvm-sh/nvm), you can run `nodenv install` in the
|
||||
> root of your repository to install the version specified in
|
||||
> [`package.json`](./package.json). Otherwise, 20.x or later should work!
|
||||
|
||||
```bash
|
||||
$ npm test
|
||||
1. :hammer_and_wrench: Install the dependencies
|
||||
|
||||
PASS ./index.test.js
|
||||
✓ throws invalid number (3ms)
|
||||
✓ wait 500 ms (504ms)
|
||||
✓ test runs (95ms)
|
||||
...
|
||||
```
|
||||
```bash
|
||||
npm install
|
||||
```
|
||||
|
||||
## Change action.yml
|
||||
1. :building_construction: Package the JavaScript for distribution
|
||||
|
||||
The action.yml defines the inputs and output for your action.
|
||||
```bash
|
||||
npm run bundle
|
||||
```
|
||||
|
||||
Update the action.yml with your name, description, inputs and outputs for your action.
|
||||
1. :white_check_mark: Run the tests
|
||||
|
||||
See the [documentation](https://help.github.com/en/articles/metadata-syntax-for-github-actions)
|
||||
```bash
|
||||
$ npm test
|
||||
|
||||
## Change the Code
|
||||
PASS ./index.test.js
|
||||
✓ throws invalid number (3ms)
|
||||
✓ wait 500 ms (504ms)
|
||||
✓ test runs (95ms)
|
||||
|
||||
Most toolkit and CI/CD operations involve async operations so the action is run in an async function.
|
||||
...
|
||||
```
|
||||
|
||||
```javascript
|
||||
const core = require('@actions/core');
|
||||
...
|
||||
## Update the Action Metadata
|
||||
|
||||
async function run() {
|
||||
try {
|
||||
...
|
||||
The [`action.yml`](action.yml) file defines metadata about your action, such as
|
||||
input(s) and output(s). For details about this file, see
|
||||
[Metadata syntax for GitHub Actions](https://docs.github.com/en/actions/creating-actions/metadata-syntax-for-github-actions).
|
||||
|
||||
When you copy this repository, update `action.yml` with the name, description,
|
||||
inputs, and outputs for your action.
|
||||
|
||||
## Update the Action Code
|
||||
|
||||
The [`src/`](./src/) directory is the heart of your action! This contains the
|
||||
source code that will be run when your action is invoked. You can replace the
|
||||
contents of this directory with your own code.
|
||||
|
||||
There are a few things to keep in mind when writing your action code:
|
||||
|
||||
- Most GitHub Actions toolkit and CI/CD operations are processed asynchronously.
|
||||
In `main.js`, you will see that the action is run in an `async` function.
|
||||
|
||||
```javascript
|
||||
const core = require('@actions/core')
|
||||
//...
|
||||
|
||||
async function run() {
|
||||
try {
|
||||
//...
|
||||
} catch (error) {
|
||||
core.setFailed(error.message)
|
||||
}
|
||||
}
|
||||
catch (error) {
|
||||
core.setFailed(error.message);
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
run()
|
||||
```
|
||||
For more information about the GitHub Actions toolkit, see the
|
||||
[documentation](https://github.com/actions/toolkit/blob/master/README.md).
|
||||
|
||||
See the [toolkit documentation](https://github.com/actions/toolkit/blob/master/README.md#packages) for the various packages.
|
||||
So, what are you waiting for? Go ahead and start customizing your action!
|
||||
|
||||
## Package for distribution
|
||||
1. Create a new branch
|
||||
|
||||
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.
|
||||
```bash
|
||||
git checkout -b releases/v1
|
||||
```
|
||||
|
||||
Actions are run from GitHub repos. Packaging the action will create a packaged action in the dist folder.
|
||||
1. Replace the contents of `src/` with your action code
|
||||
1. Add tests to `__tests__/` for your source code
|
||||
1. Format, test, and build the action
|
||||
|
||||
Run prepare
|
||||
```bash
|
||||
npm run all
|
||||
```
|
||||
|
||||
```bash
|
||||
npm run prepare
|
||||
```
|
||||
> [!WARNING]
|
||||
>
|
||||
> This step is important! It will run [`ncc`](https://github.com/vercel/ncc)
|
||||
> to build the final JavaScript action code with all dependencies included.
|
||||
> If you do not run this step, your action will not work correctly when it is
|
||||
> used in a workflow. This step also includes the `--license` option for
|
||||
> `ncc`, which will create a license file for all of the production node
|
||||
> modules used in your project.
|
||||
|
||||
Since the packaged index.js is run from the dist folder.
|
||||
1. Commit your changes
|
||||
|
||||
```bash
|
||||
git add dist
|
||||
```
|
||||
```bash
|
||||
git add .
|
||||
git commit -m "My first action is ready!"
|
||||
```
|
||||
|
||||
## Create a release branch
|
||||
1. Push them to your repository
|
||||
|
||||
Users shouldn't consume the action from master since that would be latest code and actions can break compatibility between major versions.
|
||||
```bash
|
||||
git push -u origin releases/v1
|
||||
```
|
||||
|
||||
Checkin to the v1 release branch
|
||||
|
||||
```bash
|
||||
git checkout -b v1
|
||||
git commit -a -m "v1 release"
|
||||
```
|
||||
|
||||
```bash
|
||||
git push origin v1
|
||||
```
|
||||
|
||||
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.
|
||||
1. Create a pull request and get feedback on your action
|
||||
1. Merge the pull request into the `main` branch
|
||||
|
||||
Your action is now published! :rocket:
|
||||
|
||||
See the [versioning documentation](https://github.com/actions/toolkit/blob/master/docs/action-versioning.md)
|
||||
For information about versioning your action, see
|
||||
[Versioning](https://github.com/actions/toolkit/blob/master/docs/action-versioning.md)
|
||||
in the GitHub Actions toolkit.
|
||||
|
||||
## Validate the Action
|
||||
|
||||
You can now validate the action by referencing it in a workflow file. For
|
||||
example, [`ci.yml`](./.github/workflows/ci.yml) demonstrates how to reference an
|
||||
action in the same repository.
|
||||
|
||||
```yaml
|
||||
steps:
|
||||
- name: Checkout
|
||||
id: checkout
|
||||
uses: actions/checkout@v3
|
||||
|
||||
- name: Test Local Action
|
||||
id: test-action
|
||||
uses: ./
|
||||
with:
|
||||
milliseconds: 1000
|
||||
|
||||
- name: Print Output
|
||||
id: output
|
||||
run: echo "${{ steps.test-action.outputs.time }}"
|
||||
```
|
||||
|
||||
For example workflow runs, check out the
|
||||
[Actions tab](https://github.com/actions/javascript-action/actions)! :rocket:
|
||||
|
||||
## Usage
|
||||
|
||||
You can now consume the action by referencing the v1 branch
|
||||
After testing, you can create version tag(s) that developers can use to
|
||||
reference different stable versions of your action. For more information, see
|
||||
[Versioning](https://github.com/actions/toolkit/blob/master/docs/action-versioning.md)
|
||||
in the GitHub Actions toolkit.
|
||||
|
||||
To include the action in a workflow in another repository, you can use the
|
||||
`uses` syntax with the `@` symbol to reference a specific branch, tag, or commit
|
||||
hash.
|
||||
|
||||
```yaml
|
||||
uses: actions/javascript-action@v1
|
||||
with:
|
||||
milliseconds: 1000
|
||||
```
|
||||
steps:
|
||||
- name: Checkout
|
||||
id: checkout
|
||||
uses: actions/checkout@v4
|
||||
|
||||
See the [actions tab](https://github.com/actions/javascript-action/actions) for runs of this action! :rocket:
|
||||
- name: Run my Action
|
||||
id: run-action
|
||||
uses: actions/javascript-action@v1 # Commit with the `v1` tag
|
||||
with:
|
||||
milliseconds: 1000
|
||||
|
||||
- name: Print Output
|
||||
id: output
|
||||
run: echo "${{ steps.test-action.outputs.time }}"
|
||||
```
|
||||
|
|
|
|||
Loading…
Reference in New Issue