mirror of https://github.com/actions/toolkit
Bryan MacFarlane
GitHub
parent
2a1b7d5c7e
commit
020f7034f4
|
|
@ -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.
|
||||
|
||||
[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.
|
||||
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
||||
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.
|
||||
|
||||
|
||||
|
|
|
|||
|
|
@ -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>
|
||||
Binary file not shown.
|
After Width: | Height: | Size: 62 KiB |
|
|
@ -6,32 +6,30 @@ The [javascript-template](https://github.com/actions/javascript-template) repo c
|
|||
|
||||
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).
|
||||
|
||||
|
||||
|
||||
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.
|
||||
|
||||
e.g. To use https://github.com/actions/setup-node, user's will author:
|
||||
|
||||
```yaml
|
||||
steps:
|
||||
uses: actions/setup-node@master
|
||||
```bash
|
||||
$ git clone <repolocation>
|
||||
$ cd myaction
|
||||
```
|
||||
|
||||
Update the `author` element in the package.json file.
|
||||
|
||||
# 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.
|
||||
> 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
|
||||
|
||||
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
|
||||
$ npm install
|
||||
|
|
@ -39,24 +37,24 @@ $ 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.
|
||||
Your action has a name and a description. Update all fields .
|
||||
|
||||
```yaml
|
||||
name: 'My new action'
|
||||
description: 'A test action'
|
||||
author: 'GitHub'
|
||||
name: 'Hello'
|
||||
description: 'Outputs Hello to a named input'
|
||||
author: 'me'
|
||||
inputs:
|
||||
myInput:
|
||||
description: 'Input to use'
|
||||
default: 'world'
|
||||
name:
|
||||
description: 'the name to say hello to'
|
||||
default: 'World'
|
||||
runs:
|
||||
using: 'node12'
|
||||
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:`
|
||||
|
||||
## Change Code and Add Tests
|
||||
|
|
@ -68,8 +66,8 @@ import * as core from '@actions/core';
|
|||
|
||||
async function run() {
|
||||
try {
|
||||
const myInput = core.getInput('myInput');
|
||||
core.debug(`Hello ${myInput}!`);
|
||||
const nameInput = core.getInput('name');
|
||||
console.log(`Hello ${nameInput}!`);
|
||||
} catch (error) {
|
||||
core.setFailed(error.message);
|
||||
}
|
||||
|
|
@ -78,14 +76,14 @@ async function 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
|
||||
|
||||
```bash
|
||||
$ 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
|
||||
|
||||
$ npm test
|
||||
|
|
@ -107,12 +105,12 @@ $ git add <whatever only files you added>
|
|||
$ 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
|
||||
$ git checkout -b v1-release
|
||||
$ git checkout -b releases/v1
|
||||
```
|
||||
|
||||
> 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
|
||||
steps:
|
||||
uses: {org}/{reponame}@v1-release
|
||||
uses: myorg/myaction@releases/v1
|
||||
with:
|
||||
name: World!
|
||||
```
|
||||
|
||||
## Release Current Changes as v1
|
||||
|
|
@ -154,7 +154,9 @@ Users can now reference your action in their workflows with
|
|||
|
||||
```yaml
|
||||
steps:
|
||||
uses: {org}/{reponame}@v1
|
||||
uses: myorg/myaction@v1
|
||||
with:
|
||||
name: World!
|
||||
```
|
||||
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue