2019-07-10 18:02:56 +00:00
< p align = "center" >
< img src = "res/at-logo.png" >
< / p >
2019-08-12 19:09:43 +00:00
< p align = "center" >
2020-05-07 15:39:38 +00:00
< a href = "https://github.com/actions/toolkit/actions?query=workflow%3Atoolkit-unit-tests" > < img alt = "Toolkit unit tests status" src = "https://github.com/actions/toolkit/workflows/toolkit-unit-tests/badge.svg" > < / a >
< a href = "https://github.com/actions/toolkit/actions?query=workflow%3Atoolkit-audit" > < img alt = "Toolkit audit status" src = "https://github.com/actions/toolkit/workflows/toolkit-audit/badge.svg" > < / a >
2019-08-12 19:09:43 +00:00
< / p >
2019-10-03 16:45:11 +00:00
2019-08-24 13:24:48 +00:00
## GitHub Actions Toolkit
2019-07-10 18:02:56 +00:00
2019-10-02 21:59:33 +00:00
The GitHub Actions ToolKit provides a set of packages to make creating actions easier.
2019-04-20 14:56:56 +00:00
2019-10-03 16:45:11 +00:00
< br / >
< h3 align = "center" > Get started with the < a href = "https://github.com/actions/javascript-action" > javascript-action template< / a > !< / h3 >
< br / >
2019-04-20 14:56:56 +00:00
## Packages
2019-10-02 21:59:33 +00:00
:heavy_check_mark: [@actions/core ](packages/core )
2019-08-01 15:26:17 +00:00
2019-10-02 21:59:33 +00:00
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 / >
2020-01-10 17:00:22 +00:00
:ice_cream: [@actions/glob ](packages/glob )
Provides functions to search for files matching glob patterns. Read more [here ](packages/glob )
```bash
$ npm install @actions/glob --save
```
< br / >
2019-10-02 21:59:33 +00:00
: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 / >
2019-04-22 15:46:19 +00:00
2020-02-20 20:05:07 +00:00
:floppy_disk: [@actions/artifact ](packages/artifact )
Provides functions to interact with actions artifacts. Read more [here ](packages/artifact )
```bash
$ npm install @actions/artifact --save
```
< br / >
2020-05-06 15:10:18 +00:00
:dart: [@actions/cache ](packages/cache )
2020-05-07 00:07:39 +00:00
Provides functions to cache dependencies and build outputs to improve workflow execution time.. Read more [here ](packages/cache )
2020-05-06 15:10:18 +00:00
```bash
2020-05-06 21:53:22 +00:00
$ npm install @actions/cache --save
2020-05-06 15:10:18 +00:00
```
< br / >
2019-08-01 15:26:17 +00:00
## Creating an Action with the Toolkit
2019-04-22 15:46:19 +00:00
2019-10-02 21:59:33 +00:00
:question: [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.
< br / >
< br / >
2019-10-03 16:45:11 +00:00
:curly_loop: [Versioning ](docs/action-versioning.md )
Actions are downloaded and run from the GitHub graph of repos. This contains guidance for versioning actions and safe releases.
< br / >
< br / >
2019-12-12 18:43:34 +00:00
:warning: [Problem Matchers ](docs/problem-matchers.md )
Problem Matchers are a way to scan the output of actions for a specified regex pattern and surface that information prominently in the UI.
< br / >
< br / >
2020-02-12 14:26:59 +00:00
:warning: [Proxy Server Support ](docs/proxy-support.md )
Self-hosted runners can be configured to run behind proxy servers.
< br / >
< br / >
2019-10-03 17:51:11 +00:00
< h3 > < a href = "https://github.com/actions/hello-world-javascript-action" > Hello World JavaScript Action< / a > < / h3 >
2019-10-02 21:59:33 +00:00
Illustrates how to create a simple hello world javascript action.
```javascript
...
const nameToGreet = core.getInput('who-to-greet');
console.log(`Hello ${nameToGreet}!`);
...
```
< br / >
2019-10-03 17:51:11 +00:00
< h3 > < a href = "https://github.com/actions/javascript-action" > JavaScript Action Walkthrough< / a > < / h3 >
2019-10-02 21:59:33 +00:00
2019-10-03 17:51:11 +00:00
Walkthrough and template for creating a JavaScript Action with tests, linting, workflow, publishing, and versioning.
2019-10-02 21:59:33 +00:00
2019-10-03 16:45:11 +00:00
```javascript
async function run() {
try {
const ms = core.getInput('milliseconds');
console.log(`Waiting ${ms} milliseconds ...`)
...
```
```javascript
2019-10-02 21:59:33 +00:00
PASS ./index.test.js
✓ throws invalid number
✓ wait 500 ms
✓ test runs
Test Suites: 1 passed, 1 total
Tests: 3 passed, 3 total
2019-10-03 16:45:11 +00:00
```
2019-10-02 21:59:33 +00:00
< br / >
2019-10-03 17:51:11 +00:00
< h3 > < a href = "https://github.com/actions/typescript-action" > TypeScript Action Walkthrough< / a > < / h3 >
2019-10-02 21:59:33 +00:00
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 ...`)
...
2019-10-03 16:45:11 +00:00
```
```javascript
PASS ./index.test.js
✓ throws invalid number
✓ wait 500 ms
✓ test runs
2019-10-02 21:59:33 +00:00
2019-10-03 16:45:11 +00:00
Test Suites: 1 passed, 1 total
Tests: 3 passed, 3 total
2019-10-02 21:59:33 +00:00
```
< br / >
< br / >
2019-10-03 17:51:11 +00:00
< h3 > < a href = "docs/container-action.md" > Docker Action Walkthrough< / a > < / h3 >
2019-10-02 21:59:33 +00:00
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 / >
2019-04-22 15:46:19 +00:00
2019-10-03 17:51:11 +00:00
< h3 > < a href = "https://github.com/actions/container-toolkit-action" > Docker Action Walkthrough with Octokit< / a > < / h3 >
2019-09-11 07:35:39 +00:00
2019-10-02 21:59:33 +00:00
Create an action that is delivered as a container which uses the toolkit. This example uses the GitHub context to construct an Octokit client.
2019-09-11 07:35:39 +00:00
2019-10-03 16:45:11 +00:00
```docker
FROM node:slim
COPY . .
RUN npm install --production
ENTRYPOINT ["node", "/lib/main.js"]
```
2019-10-02 21:59:33 +00:00
```javascript
2019-10-03 16:45:11 +00:00
const myInput = core.getInput('myInput');
core.debug(`Hello ${myInput} from inside a container`);
2019-04-22 15:46:19 +00:00
2019-10-03 16:45:11 +00:00
const context = github.context;
console.log(`We can even get context data, like the repo: ${context.repo.repo}`)
2019-10-02 21:59:33 +00:00
```
< br / >
2019-04-22 15:46:19 +00:00
2019-08-01 15:26:17 +00:00
## Contributing
2019-04-22 15:46:19 +00:00
2020-03-17 15:57:32 +00:00
We welcome contributions. See [how to contribute ](.github/CONTRIBUTING.md ).
2019-10-09 12:47:27 +00:00
## Code of Conduct
See [our code of conduct ](CODE_OF_CONDUCT.md ).