mirror of https://github.com/actions/toolkit
Format README and update links
parent
3825457cfc
commit
7421c8a883
193
README.md
193
README.md
|
@ -1,6 +1,7 @@
|
|||
<!-- markdownlint-disable MD033 MD041 -->
|
||||
|
||||
<p align="center">
|
||||
<img src="res/at-logo.png">
|
||||
<img alt="Logo" src="res/at-logo.png">
|
||||
</p>
|
||||
|
||||
<p align="center">
|
||||
|
@ -8,219 +9,139 @@
|
|||
<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>
|
||||
</p>
|
||||
|
||||
|
||||
## GitHub Actions Toolkit
|
||||
|
||||
The GitHub Actions ToolKit provides a set of packages to make creating actions easier.
|
||||
The GitHub Actions Toolkit provides a set of packages to make creating actions easier.
|
||||
|
||||
<br/>
|
||||
<h3 align="center">Get started with the <a href="https://github.com/actions/javascript-action">javascript-action template</a>!</h3>
|
||||
<br/>
|
||||
<h3 align="center">
|
||||
Get started with the <a href="https://github.com/actions/typescript-action">TypeScript Action Template</a>!
|
||||
</h3>
|
||||
|
||||
## Packages
|
||||
|
||||
:heavy_check_mark: [@actions/core](packages/core)
|
||||
### :heavy_check_mark: [@actions/core](packages/core)
|
||||
|
||||
Provides functions for inputs, outputs, results, logging, secrets and variables. Read more [here](packages/core)
|
||||
Provides functions for managing inputs, outputs, results, logging, secrets and variables.
|
||||
|
||||
```bash
|
||||
$ npm install @actions/core
|
||||
npm install @actions/core
|
||||
```
|
||||
<br/>
|
||||
|
||||
:runner: [@actions/exec](packages/exec)
|
||||
### :runner: [@actions/exec](packages/exec)
|
||||
|
||||
Provides functions to exec cli tools and process output. Read more [here](packages/exec)
|
||||
Provides functions to run CLI tools and process output.
|
||||
|
||||
```bash
|
||||
$ npm install @actions/exec
|
||||
npm install @actions/exec
|
||||
```
|
||||
<br/>
|
||||
|
||||
:ice_cream: [@actions/glob](packages/glob)
|
||||
### :ice_cream: [@actions/glob](packages/glob)
|
||||
|
||||
Provides functions to search for files matching glob patterns. Read more [here](packages/glob)
|
||||
Provides functions to search for files matching glob patterns.
|
||||
|
||||
```bash
|
||||
$ npm install @actions/glob
|
||||
npm install @actions/glob
|
||||
```
|
||||
<br/>
|
||||
|
||||
:phone: [@actions/http-client](packages/http-client)
|
||||
### :phone: [@actions/http-client](packages/http-client)
|
||||
|
||||
A lightweight HTTP client optimized for building actions. Read more [here](packages/http-client)
|
||||
Provides a lightweight HTTP client optimized for building actions.
|
||||
|
||||
```bash
|
||||
$ npm install @actions/http-client
|
||||
npm install @actions/http-client
|
||||
```
|
||||
<br/>
|
||||
|
||||
:pencil2: [@actions/io](packages/io)
|
||||
### :pencil2: [@actions/io](packages/io)
|
||||
|
||||
Provides disk i/o functions like cp, mv, rmRF, which etc. Read more [here](packages/io)
|
||||
Provides disk I/O functions like `cp`, `mv`, `rmRF`, `which`, etc.
|
||||
|
||||
```bash
|
||||
$ npm install @actions/io
|
||||
npm install @actions/io
|
||||
```
|
||||
<br/>
|
||||
|
||||
:hammer: [@actions/tool-cache](packages/tool-cache)
|
||||
### :hammer: [@actions/tool-cache](packages/tool-cache)
|
||||
|
||||
Provides functions for downloading and caching tools. e.g. setup-* actions. Read more [here](packages/tool-cache)
|
||||
|
||||
See @actions/cache for caching workflow dependencies.
|
||||
Provides functions for downloading and caching tools (e.g. `setup-*` actions). See [`@actions/cache`](packages/cache) for caching workflow dependencies.
|
||||
|
||||
```bash
|
||||
$ npm install @actions/tool-cache
|
||||
npm install @actions/tool-cache
|
||||
```
|
||||
<br/>
|
||||
|
||||
:octocat: [@actions/github](packages/github)
|
||||
### :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)
|
||||
Provides an Octokit client hydrated with the context of the current workflow run.
|
||||
|
||||
```bash
|
||||
$ npm install @actions/github
|
||||
npm install @actions/github
|
||||
```
|
||||
<br/>
|
||||
|
||||
:floppy_disk: [@actions/artifact](packages/artifact)
|
||||
### :floppy_disk: [@actions/artifact](packages/artifact)
|
||||
|
||||
Provides functions to interact with actions artifacts. Read more [here](packages/artifact)
|
||||
Provides functions to interact with artifacts.
|
||||
|
||||
```bash
|
||||
$ npm install @actions/artifact
|
||||
npm install @actions/artifact
|
||||
```
|
||||
<br/>
|
||||
|
||||
:dart: [@actions/cache](packages/cache)
|
||||
### :dart: [@actions/cache](packages/cache)
|
||||
|
||||
Provides functions to cache dependencies and build outputs to improve workflow execution time. Read more [here](packages/cache)
|
||||
Provides functions to cache dependencies and build outputs to improve workflow run duration.
|
||||
|
||||
```bash
|
||||
$ npm install @actions/cache
|
||||
npm install @actions/cache
|
||||
```
|
||||
<br/>
|
||||
|
||||
## Creating an Action with the Toolkit
|
||||
## Creating Custom GitHub Actions
|
||||
|
||||
:question: [Choosing an action type](docs/action-types.md)
|
||||
:question: [Types of actions](https://docs.github.com/en/actions/creating-actions/about-custom-actions#types-of-actions)
|
||||
|
||||
Outlines the differences and why you would want to create a JavaScript or a container based action.
|
||||
<br/>
|
||||
<br/>
|
||||
You can build Docker container, JavaScript, and composite actions.
|
||||
|
||||
:curly_loop: [Versioning](docs/action-versioning.md)
|
||||
:curly_loop: [Using release management for actions](https://docs.github.com/en/actions/creating-actions/about-custom-actions#using-release-management-for-actions)
|
||||
|
||||
Actions are downloaded and run from the GitHub graph of repos. This contains guidance for versioning actions and safe releases.
|
||||
<br/>
|
||||
<br/>
|
||||
This section explains how you can use release management to distribute updates to your actions in a predictable way.
|
||||
|
||||
: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/>
|
||||
Problem Matchers are a way to scan the output of actions for a specified regular expression pattern and surface that information prominently in the UI.
|
||||
|
||||
:warning: [Proxy Server Support](docs/proxy-support.md)
|
||||
:warning: [Using a proxy server with self-hosted runners](https://docs.github.com/en/actions/hosting-your-own-runners/managing-self-hosted-runners/using-a-proxy-server-with-self-hosted-runners)
|
||||
|
||||
Self-hosted runners can be configured to run behind proxy servers.
|
||||
<br/>
|
||||
<br/>
|
||||
You can configure self-hosted runners to use a proxy server to communicate with GitHub.
|
||||
|
||||
<h3><a href="https://github.com/actions/hello-world-javascript-action">Hello World JavaScript Action</a></h3>
|
||||
## Templates and Examples
|
||||
|
||||
Illustrates how to create a simple hello world javascript action.
|
||||
### [`actions/typescript-action`](https://github.com/actions/typescript-action)
|
||||
|
||||
```javascript
|
||||
...
|
||||
const nameToGreet = core.getInput('who-to-greet');
|
||||
console.log(`Hello ${nameToGreet}!`);
|
||||
...
|
||||
```
|
||||
<br/>
|
||||
Template action written in TypeScript with compilation, tests, linting, publishing, and versioning.
|
||||
|
||||
<h3><a href="https://github.com/actions/javascript-action">JavaScript Action Walkthrough</a></h3>
|
||||
### [`action/javascript-action`](https://github.com/actions/javascript-action)
|
||||
|
||||
Walkthrough and template for creating a JavaScript Action with tests, linting, workflow, publishing, and versioning.
|
||||
Template action written in JavaScript with compilation, tests, linting, publishing, and versioning.
|
||||
|
||||
```javascript
|
||||
async function run() {
|
||||
try {
|
||||
const ms = core.getInput('milliseconds');
|
||||
console.log(`Waiting ${ms} milliseconds ...`)
|
||||
...
|
||||
```
|
||||
```javascript
|
||||
PASS ./index.test.js
|
||||
✓ throws invalid number
|
||||
✓ wait 500 ms
|
||||
✓ test runs
|
||||
### [`actions/container-action`](https://github.com/actions/container-action)
|
||||
|
||||
Test Suites: 1 passed, 1 total
|
||||
Tests: 3 passed, 3 total
|
||||
```
|
||||
<br/>
|
||||
Template action deployed as a Docker conatiner with compilation, tests, linting, publishing, and versioning.
|
||||
|
||||
<h3><a href="https://github.com/actions/typescript-action">TypeScript Action Walkthrough</a></h3>
|
||||
### [`actions/container-toolkit-action`](https://github.com/actions/container-toolkit-action)
|
||||
|
||||
Walkthrough creating a TypeScript Action with compilation, tests, linting, workflow, publishing, and versioning.
|
||||
Template action deployed as a Docker conatiner with compilation, tests, linting, publishing, and versioning. Demonstrates using the GitHub Actions Toolkit within custom actions.
|
||||
|
||||
```javascript
|
||||
import * as core from '@actions/core';
|
||||
### [`actions/container-prebuilt-action`](https://github.com/actions/container-prebuilt-action)
|
||||
|
||||
async function run() {
|
||||
try {
|
||||
const ms = core.getInput('milliseconds');
|
||||
console.log(`Waiting ${ms} milliseconds ...`)
|
||||
...
|
||||
```
|
||||
```javascript
|
||||
PASS ./index.test.js
|
||||
✓ throws invalid number
|
||||
✓ wait 500 ms
|
||||
✓ test runs
|
||||
Template action deployed as a Docker conatiner with compilation, tests, linting, publishing, and versioning. Demonstrates reduced workflow run duration using prebuilt container images.
|
||||
|
||||
Test Suites: 1 passed, 1 total
|
||||
Tests: 3 passed, 3 total
|
||||
```
|
||||
<br/>
|
||||
<br/>
|
||||
### [`actions/hello-world-javascript-action`](https://github.com/actions/hello-world-javascript-action)
|
||||
|
||||
<h3><a href="docs/container-action.md">Docker Action Walkthrough</a></h3>
|
||||
Illustrates how to create a simple _Hello, World!_ action written in JavaScript.
|
||||
|
||||
Create an action that is delivered as a container and run with docker.
|
||||
### [`actions/hello-world-docker-action`](https://github.com/actions/hello-world-docker-action)
|
||||
|
||||
```docker
|
||||
FROM alpine:3.10
|
||||
COPY LICENSE README.md /
|
||||
COPY entrypoint.sh /entrypoint.sh
|
||||
ENTRYPOINT ["/entrypoint.sh"]
|
||||
```
|
||||
<br/>
|
||||
|
||||
<h3><a href="https://github.com/actions/container-toolkit-action">Docker Action Walkthrough with Octokit</a></h3>
|
||||
|
||||
Create an action that is delivered as a container which uses the toolkit. This example uses the GitHub context to construct an Octokit client.
|
||||
|
||||
```docker
|
||||
FROM node:slim
|
||||
COPY . .
|
||||
RUN npm install --production
|
||||
ENTRYPOINT ["node", "/lib/main.js"]
|
||||
```
|
||||
```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/>
|
||||
Illustrates how to create a simple _Hello, World!_ action written as a Docker container.
|
||||
|
||||
## Contributing
|
||||
|
||||
We welcome contributions. See [how to contribute](.github/CONTRIBUTING.md).
|
||||
We welcome contributions! See [how to contribute](.github/CONTRIBUTING.md).
|
||||
|
||||
## Code of Conduct
|
||||
|
||||
|
|
Loading…
Reference in New Issue