actions
/
toolkit
mirror of https://github.com/actions/toolkit
1
0
Fork 0
Code

JavaScript walk through update (#107) 

* update walkthrough

* review feedback
pull/113/head
Bryan MacFarlane 2019-09-04 17:30:45 -04:00 committed by GitHub
parent 2a1b7d5c7e
commit 020f7034f4
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
5 changed files with 41 additions and 32 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
README.md
View File

@ -27,9 +27,9 @@ The toolkit provides five separate packages. See the docs for each action.
Actions are units of work which can either run in a container or on the host machine. Actions are units of work which can either run in a container or on the host machine.
[Choosing an action type](docs/action-types.md): Outlines the differences and why you would want to create a host or a container based action. [Choosing an action type](docs/action-types.md): Outlines the differences and why you would want to create a JavaScript or a container based action.
[JavaScript Action Walkthrough](docs/javascript-action.md): A full walkthrough creating an action using the toolkit along with TypeScript and Jest for unit testing. It also covers a branching strategy for versioning and safely testing and releasing an action. [JavaScript Action Walkthrough using a Template](docs/javascript-action.md): A full walkthrough creating an action using the toolkit along with TypeScript for compile time support and Jest for unit testing. It also covers a branching strategy for versioning and safely testing and releasing an action.
[Docker Action Walkthrough](docs/container-action.md): Create an action that is delivered as a container and run with docker. [Docker Action Walkthrough](docs/container-action.md): Create an action that is delivered as a container and run with docker.

6
docs/action-versioning.md
View File

@ -41,3 +41,9 @@ git push origin v1
5. **Compatibility Breaks**: introduce a new major version branch (releases/v2) and tag (v2) if changes will break existing workflows. For example, changing inputs. 5. **Compatibility Breaks**: introduce a new major version branch (releases/v2) and tag (v2) if changes will break existing workflows. For example, changing inputs.
See [Git-Basics-Tagging](https://git-scm.com/book/en/v2/Git-Basics-Tagging) See [Git-Basics-Tagging](https://git-scm.com/book/en/v2/Git-Basics-Tagging)
# Sample Workflow
This illustrates one possible versioning workflow which the walk through covered.
![versioning](assets/action-releases.png)

1
docs/assets/action-releases.drawio Normal file
View File

@ -0,0 +1 @@
<mxfile modified="2019-09-04T11:27:58.307Z" host="www.draw.io" agent="Mozilla/5.0 (Macintosh; Intel Mac OS X 10_14_6) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/76.0.3809.100 Safari/537.36" etag="MFzGVuAX-y50cwbudjLg" version="11.2.5" type="device" pages="1"><diagram name="Page-1" id="ff44883e-f642-bcb2-894b-16b3d25a3f0b">7Vtbc5s4GP01nj4lA+L+WCdp96E70910uu1TB4OMmWDkEdhx9tfvJ5AMSPIta4Mbx5mJ0R10zncVHll38/VnGi5mf5IYZyNkxOuRdT9CyHds+M8qXuoKxzPqioSmcV1lNhWP6b+YV4puyzTGRadjSUhWpotuZUTyHEdlpy6klDx3u01J1l11ESZYqXiMwkzU3jpN/T9pXM54vekGTcMfOE1mfHEfuXXDJIyeEkqWOV9xhKxp9amb56GYiz9qMQtj8tyqsh5G1h0lpKyv5us7nLHNFRsnxpUv4m5H1nhWzjMomHBZNX/aMtg8ZDA8HMV52V5u23xTYxJFQWAZNnanTngTKPPjGHaWF3OSw9c4WtIVjvmKrcWLMqQlJwMwwRrjPP7I0IRylIVFkUZ15ac0E2Og1B5RlJQ84TuSEVotbxnVZ9MisGSPPSX5ZjVUTVXSlx+beaHwEwoGUIEX7xm9jU3pRZTWafmjdd0aBaVmECuIMeo+C2TIkkZYv7mIS0JIE1zqu/BZ2Ka3puXYfcZkjuHOoQPFWVimq64QhFxqkk2/zdCvJIUbRQYXcFsIKpdvT8i3mKJ+DD6q4Q9ctG6jqapYdRjDTPfUFNvHpp2c0WG/E/kNy1rE+tkm3RaWvYox1n7GoH4YY0mM8WXG1Pd4FsbUC63CbMnvPlLVIEwBxoVR53mWlvhxEVZ7+gzmrcugSrVX1KoYIrS3qVM+bvVRiGR3iWSxicIsTXKm5wBeTFkHYGVrqqnD/nbxYIVpidc7MeStyO9isbHOz42lE11mbRtnbEe9g9cx4Kjm7NLEeY8qf63ZeJVAuxcj0E4gkcjqTaCRKtBoUIE2BxZo27scgbZUcKyrBseRwPHRcODYKjjOVYPjyVpsSFNov5vCI0yhvd8Uuv2YQs8azBS6qkBrWHRFAu3awwl08ovef//7r+Rhtfj+7UtBvkR3N5roY4TcDFYdT+AiqS5omEdwbx9FCyy0aYTvcM5wyicF+wKu4rDABfRZqWEMYLZgl1GYZWRZ7od8gWkKD8pgEYO+NlXjBSnSMiU5quTY9E9kEiWt69kqSCbqEyWNSznD0VOas0elJGa5TLwAJYrzKGWbzyGkAqZvuGAa4QE9KJjAppSyrm4LE1fsbaHgVYrgsC1OAaaPvGGexnG2TbC70nwK2XKdrifja2DTCRc6F2waZ1OTHroi9ee7wzmbWoTefZpdPs0uUu9ybKx+HBsnMG890/GQ7zng1XhBl1u2tnVPClhdBHUp67pn85602+0oOmSartmgolgyTW9MKZkzPEDDp3nydtW7Z3TVu2vZqno3+lTvl5nq3yiMgZP9r1Uedj/Kw5fzHgeeESkTubJNO9/RgXZLPUVBzDEsCFUgzGybJuCPv1214DuSftZEVHafWsFX8FAiqojisMQ1h3GFDtzMuJKLZGucZZi3EOKorr0y+85Jeg/KwO6eRv17clBmqurf7dN3DPYDfVToPA8LtoG/Z8yMpJjZDoaOmcXRXTv68lSLfUXRV3BxySfNQfcFeFBHhF+v94QEPc/u5xiSfZQN36F+juwwuWa/fo6pSYL51y3Pgd/1PIfOppiao9TfS577T6cIWrdDol2h03tcdCgZLzO3d2uDlDSEvDFujQMpeWSQziZp+X190bQvuxbIb+zJp5oH2zXJK+o7wWeqGb6rCuBNQ/ZQPEsxY71G8KZ6bF3nXCfLN5xf9QPZUVTzq/3CoGa2ytYxJgjGFFN24Mmy3oZ08Gzw0BsZH0DNwLAPcLnMea/47cIY2N1jkMBAA8N41oQYOiAhNicrvG+u3vNilv73LMfj7Xfx1r6s0GtezFQTY1tSW5chdJWrxm9KCunYxp/Exsnv8QWBApIOo7MJpZi4hdHuN3euByp/i1+5L5F5Pqx072jJkU3zUzS+7XFYzHSBzcFbtteBb22Io9kPUfc//XwZD09OOx3q55umfIJwsgQWFJtfRNbdm9+dWg//AQ==</diagram></mxfile>

BIN
docs/assets/action-releases.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 62 KiB

62
docs/javascript-action.md
View File

@ -6,32 +6,30 @@ The [javascript-template](https://github.com/actions/javascript-template) repo c
Navigate to https://github.com/actions/javascript-template Navigate to https://github.com/actions/javascript-template
Click on `Use this template` to create the repo for your action. Click on `Use this template` to create the repo for your action. Provide a name such as `myaction` (used in rest of walk through).
![template](assets/node12-template.png) ![template](assets/node12-template.png)
Complete creating your repo and clone the repo. # Clone and Update
> NOTE: The location of the repo will be how users will reference your action in their workflow file with the using keyword. ```bash
$ git clone <repolocation>
e.g. To use https://github.com/actions/setup-node, user's will author: $ cd myaction
```yaml
steps:
uses: actions/setup-node@master
``` ```
Update the `author` element in the package.json file.
# Dev Workflow # Dev Workflow
The workflow below describes one possible workflow with a branching strategy. Others exist. 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. > Key Point: the branch that users reference in their workflow files should reference an action from a distribution branch that **only** has 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. The workflow below describes a strategy where you code in master (with node_modules ignored) with a distribution releases/v1 branch users reference via a tag. Actions are self contained referenced from the github graph of repos, downloaded by the runner and run intact at runtime.
## Install Dependencies ## 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 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. node_modules are ignored in the coding master branch.
```bash ```bash
$ npm install $ npm install
@ -39,24 +37,24 @@ $ npm install
## Define Metadata ## Define Metadata
Your action has a name and a description. Update the author. Your action has a name and a description. Update all fields .
Create inputs that your unit of work will need. These will be what workflow authors set with the `with:` keyword.
```yaml ```yaml
name: 'My new action' name: 'Hello'
description: 'A test action' description: 'Outputs Hello to a named input'
author: 'GitHub' author: 'me'
inputs: inputs:
myInput: name:
description: 'Input to use' description: 'the name to say hello to'
default: 'world' default: 'World'
runs: runs:
using: 'node12' using: 'node12'
main: 'lib/main.js' main: 'lib/main.js'
``` ```
The `name` input will be referenced by workflow authors using the `with:` keyword.
Note that the action will be run with node 12 (carried by the runner) and the entry point is specified with `main:` 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 ## Change Code and Add Tests
@ -68,8 +66,8 @@ import * as core from '@actions/core';
async function run() { async function run() {
try { try {
const myInput = core.getInput('myInput'); const nameInput = core.getInput('name');
core.debug(`Hello ${myInput}!`); console.log(`Hello ${nameInput}!`);
} catch (error) { } catch (error) {
core.setFailed(error.message); core.setFailed(error.message);
} }
@ -78,14 +76,14 @@ async function run() {
run(); run();
``` ```
Modify tests in `__tests__/main.test.ts`. The template uses [jest](https://github.com/facebook/jest). Note that tests are in `__tests__/main.test.ts`. The template uses [jest](https://github.com/facebook/jest) to get you started with unit testing.
## Build and Test ## Build and Test
```bash ```bash
$ npm run build $ npm run build
> node12-template-action@0.0.0 build /Users/user/Projects/testnode12 > javascript-template-action@0.0.0 build /Users/user/Projects/myaction
> tsc > tsc
$ npm test $ npm test
@ -107,12 +105,12 @@ $ git add <whatever only files you added>
$ git commit -m "Message" $ git commit -m "Message"
``` ```
## Publish a v1-release Action ## Publish a releases/v1 Action
After changing some files, create a v1-release branch which we will release After changing some files, create a releases/v1 branch which we will release
```bash ```bash
$ git checkout -b v1-release $ git checkout -b releases/v1
``` ```
> NOTE: We will provide tooling and an action to automate this soon. > NOTE: We will provide tooling and an action to automate this soon.
@ -139,7 +137,9 @@ Once the action has a self contained version in the v1-release branch, you can t
```yaml ```yaml
steps: steps:
uses: {org}/{reponame}@v1-release uses: myorg/myaction@releases/v1
with:
name: World!
``` ```
## Release Current Changes as v1 ## Release Current Changes as v1
@ -154,7 +154,9 @@ Users can now reference your action in their workflows with
```yaml ```yaml
steps: steps:
uses: {org}/{reponame}@v1 uses: myorg/myaction@v1
with:
name: World!
``` ```