mirror of https://github.com/actions/toolkit
153 lines
3.4 KiB
Markdown
153 lines
3.4 KiB
Markdown
# Creating a JavaScript Action
|
|
|
|
The [node12-template](https://github.com/actions/node12-template) repo contains everything you need to get started.
|
|
|
|
# Create a Repo from the Template
|
|
|
|
Navigate to https://github.com/actions/node12-template
|
|
|
|
Click on `Use this template` to create the repo for your action.
|
|
|
|
|
|
|
|
Complete creating your repo and clone the repo.
|
|
|
|
> NOTE: The location of the repo will be how users will reference your action in their workflow file with the using keyword.
|
|
|
|
e.g. To use https://github.com/actions/setup-node, user's will author:
|
|
|
|
```yaml
|
|
steps:
|
|
using: actions/setup-node@master
|
|
```
|
|
|
|
# Dev Workflow
|
|
|
|
The workflow below describes one possible workflow with a branching strategy. Others exist.
|
|
|
|
> Key Point: the branch that users reference in their workflow files should reference an action that has **only** the production dependencies.
|
|
|
|
The workflow below describes a strategy where you code in master (with node_modules ignored) with a v1 branch users reference and contains the product references. Actions are self contained referenced on the github graph of repos.
|
|
|
|
## Install Dependencies
|
|
|
|
After creating a repo from the template and cloning it, you will be in master. The command below will install the toolkit, other dependencies and dev dependencies
|
|
|
|
```bash
|
|
$ npm install
|
|
```
|
|
|
|
## Define Metadata
|
|
|
|
Your action has a name and a description. Update the author.
|
|
|
|
Create inputs that your unit of work will need. These will be what workflow authors set with the `with:` keyword.
|
|
|
|
```yaml
|
|
name: 'My new action'
|
|
description: 'A test action'
|
|
author: 'GitHub'
|
|
inputs:
|
|
myInput:
|
|
description: 'Input to use'
|
|
default: 'world'
|
|
runs:
|
|
using: 'node12'
|
|
main: 'lib/main.js'
|
|
|
|
```
|
|
|
|
Note that the action will be run with node 12 (carried by the runner) and the entry point is specified with `main:`
|
|
|
|
## Change Code and Add Tests
|
|
|
|
The entry point is in main.ts
|
|
|
|
```typescript
|
|
import * as core from '@actions/core';
|
|
|
|
async function run() {
|
|
try {
|
|
const myInput = core.getInput('myInput');
|
|
core.debug(`Hello ${myInput}!`);
|
|
} catch (error) {
|
|
core.setFailed(error.message);
|
|
}
|
|
}
|
|
|
|
run();
|
|
```
|
|
|
|
Modify tests in `__tests__\main.test.ts`. The template uses [jest](https://github.com/facebook/jest).
|
|
|
|
## Format the Code
|
|
|
|
```bash
|
|
$ npm run format
|
|
```
|
|
|
|
## Build and Test
|
|
|
|
```bash
|
|
$ npm run build
|
|
|
|
> node12-template-action@0.0.0 build /Users/user/Projects/testnode12
|
|
> tsc
|
|
|
|
$ npm test
|
|
|
|
> jest
|
|
|
|
PASS __tests__/main.test.ts
|
|
TODO - Add a test suite
|
|
✓ TODO - Add a test (1ms)
|
|
|
|
Test Suites: 1 passed, 1 total
|
|
...
|
|
```
|
|
|
|
## Commit and Push Changes
|
|
|
|
```bash
|
|
$ git add <whatever only files you added>
|
|
$ git commit -m "Message"
|
|
```
|
|
|
|
## Publish a v1 Action
|
|
|
|
After changing some files, create a v1 branch which we will release
|
|
|
|
```bash
|
|
$ git checkout -b v1
|
|
```
|
|
|
|
> NOTE: We will provide tooling and an action to automate this soon.
|
|
|
|
Checkin production dependencies:
|
|
1. **Do not ignore node_modules**: Add a `!` in front of the `node_modules` line.
|
|
2. **Delete node_modules**: rm -Rf node_modules
|
|
3. **Install production dependencies**: npm install --production
|
|
4. **Add**: git add node_modules
|
|
|
|
|
|
Simply commit and push your action to publish.
|
|
|
|
```bash
|
|
$ git commit -a -m "publishing v1 of action"
|
|
$ git push
|
|
```
|
|
|
|
> NOTE: Consider versioning your actions with tags. See [versioning](docs/action-versioning.md)
|
|
|
|
# Users Referencing
|
|
|
|
Users can now reference your action in their workflows with
|
|
|
|
```yaml
|
|
steps:
|
|
using: {org}/{reponame}@v1
|
|
```
|
|
|
|
|
|
|