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

Update readme (#178) 

Updating readme
pull/183/head
Bryan MacFarlane 2019-10-02 17:59:33 -04:00 committed by GitHub
parent 531da1858f
commit f210cdb256
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 130 additions and 17 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

147
README.md
View File

@ -9,37 +9,150 @@
## GitHub Actions Toolkit
The GitHub Actions ToolKit provides a set of packages to make creating actions easier and drive consistency.
The GitHub Actions ToolKit provides a set of packages to make creating actions easier.
## Packages
The toolkit provides five separate packages. See the docs for each action.
:heavy_check_mark: [@actions/core](packages/core)
| Package | Description |
| ------- | ----------- |
| [@actions/core](packages/core) | Core functions for getting inputs, setting outputs, setting results, logging, secrets and environment variables |
| [@actions/exec](packages/exec) | Functions necessary for running tools on the command line |
| [@actions/io](packages/io) | Core functions for CLI filesystem scenarios |
| [@actions/tool-cache](packages/tool-cache) | Functions necessary for downloading and caching tools |
| [@actions/github](packages/github) | An Octokit client hydrated with the context that the current action is being run in |
Provides functions for inputs, outputs, results, logging, secrets and variables. Read more [here](packages/core)
```bash
$ npm install @actions/core --save
```
<br/>
:runner: [@actions/exec](packages/exec)
Provides functions to exec cli tools and process output. Read more [here](packages/exec)
```bash
$ npm install @actions/exec --save
```
<br/>
:pencil2: [@actions/io](packages/io)
Provides disk i/o functions like cp, mv, rmRF, find etc. Read more [here](packages/io)
```bash
$ npm install @actions/io --save
```
<br/>
:hammer: [@actions/tool-cache](packages/tool-cache)
Provides functions for downloading and caching tools. e.g. setup-* actions. Read more [here](packages/tool-cache)
```bash
$ npm install @actions/tool-cache --save
```
<br/>
:octocat: [@actions/github](packages/github)
Provides an Octokit client hydrated with the context that the current action is being run in. Read more [here](packages/github)
```bash
$ npm install @actions/github --save
```
<br/>
## Creating an Action with the Toolkit
Actions run in a container or on the host machine.
:question: [Choosing an action type](docs/action-types.md)
[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.
Outlines the differences and why you would want to create a JavaScript or a container based action.
<br/>
<br/>
[Hello World JavaScript Action](https://github.com/actions/hello-world-javascript-action): Illustrates how to create a simple hello world javascript action.
[Hello World JavaScript Action](https://github.com/actions/hello-world-javascript-action)
[JavaScript Action Walkthrough](https://github.com/actions/javascript-action): Walkthrough creating a JavaScript Action with tests, linting, workflow, publishing, and versioning.
Illustrates how to create a simple hello world javascript action.
[TypeScript Action Walkthrough](https://github.com/actions/typescript-action): Walkthrough creating a TypeScript Action with compilation, tests, linting, workflow, publishing, and versioning.
```javascript
...
const nameToGreet = core.getInput('who-to-greet');
console.log(`Hello ${nameToGreet}!`);
...
```
<br/>
<br/>
[Docker Action Walkthrough](docs/container-action.md): Create an action that is delivered as a container and run with docker.
[JavaScript Action Walkthrough](https://github.com/actions/javascript-action)
[Docker Action Walkthrough with Octokit](docs/container-action-toolkit.md): Create an action that is delivered as a container which uses the toolkit. This example uses the GitHub context to construct an Octokit client.
Walkthrough and template for creating a JavaScript Action with tests, linting, workflow, publishing, and versioning.
[Versioning](docs/action-versioning.md): Recommendations on versioning, releases and tagging your action.
```javascript
PASS ./index.test.js
✓ throws invalid number
✓ wait 500 ms
✓ test runs
Test Suites: 1 passed, 1 total
Tests: 3 passed, 3 total
```
<br/>
<br/>
[TypeScript Action Walkthrough](https://github.com/actions/typescript-action)
Walkthrough creating a TypeScript Action with compilation, tests, linting, workflow, publishing, and versioning.
```javascript
import * as core from '@actions/core';
async function run() {
try {
const ms = core.getInput('milliseconds');
console.log(`Waiting ${ms} milliseconds ...`)
...
} catch (error) {
core.setFailed(error.message);
}
}
run();
```
<br/>
<br/>
[Docker Action Walkthrough](docs/container-action.md)
Create an action that is delivered as a container and run with docker.
```docker
FROM alpine:3.10
COPY LICENSE README.md /
COPY entrypoint.sh /entrypoint.sh
ENTRYPOINT ["/entrypoint.sh"]
```
<br/>
<br/>
[Docker Action Walkthrough with Octokit](https://github.com/actions/container-toolkit-action)
Create an action that is delivered as a container which uses the toolkit. This example uses the GitHub context to construct an Octokit client.
```javascript
const myInput = core.getInput('myInput');
core.debug(`Hello ${myInput} from inside a container`);
const context = github.context;
console.log(`We can even get context data, like the repo: ${context.repo.repo}`)
```
<br/>
<br/>
:curly_loop: [Versioning](docs/action-versioning.md)
Recommendations on versioning, releases and tagging your action.
<br/>
<br/>
## Contributing