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

Format README and update links

pull/1632/head
Nick Alteen 2024-01-26 23:04:48 -05:00
parent 3825457cfc
commit 7421c8a883
1 changed files with 57 additions and 136 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

193
README.md
View File

@ -1,6 +1,7 @@
<!-- markdownlint-disable MD033 MD041 -->
<p align="center"> <p align="center">
<img src="res/at-logo.png"> <img alt="Logo" src="res/at-logo.png">
</p> </p>
<p align="center"> <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> <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> </p>
## GitHub Actions Toolkit ## 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">
<h3 align="center">Get started with the <a href="https://github.com/actions/javascript-action">javascript-action template</a>!</h3> Get started with the <a href="https://github.com/actions/typescript-action">TypeScript Action Template</a>!
<br/> </h3>
## Packages ## 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 ```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 ```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 ```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 ```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 ```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) Provides functions for downloading and caching tools (e.g. `setup-*` actions). See [`@actions/cache`](packages/cache) for caching workflow dependencies.
See @actions/cache for caching workflow dependencies.
```bash ```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 ```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 ```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 ```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. You can build Docker container, JavaScript, and composite actions.
<br/>
<br/>
: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. This section explains how you can use release management to distribute updates to your actions in a predictable way.
<br/>
<br/>
:warning: [Problem Matchers](docs/problem-matchers.md) :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. 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.
<br/>
<br/>
: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. You can configure self-hosted runners to use a proxy server to communicate with GitHub.
<br/>
<br/>
<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 Template action written in TypeScript with compilation, tests, linting, publishing, and versioning.
...
const nameToGreet = core.getInput('who-to-greet');
console.log(`Hello ${nameToGreet}!`);
...
```
<br/>
<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 ### [`actions/container-action`](https://github.com/actions/container-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
Test Suites: 1 passed, 1 total Template action deployed as a Docker conatiner with compilation, tests, linting, publishing, and versioning.
Tests: 3 passed, 3 total
```
<br/>
<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 ### [`actions/container-prebuilt-action`](https://github.com/actions/container-prebuilt-action)
import * as core from '@actions/core';
async function run() { Template action deployed as a Docker conatiner with compilation, tests, linting, publishing, and versioning. Demonstrates reduced workflow run duration using prebuilt container images.
try {
const ms = core.getInput('milliseconds');
console.log(`Waiting ${ms} milliseconds ...`)
...
```
```javascript
PASS ./index.test.js
✓ throws invalid number
✓ wait 500 ms
✓ test runs
Test Suites: 1 passed, 1 total ### [`actions/hello-world-javascript-action`](https://github.com/actions/hello-world-javascript-action)
Tests: 3 passed, 3 total
```
<br/>
<br/>
<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 Illustrates how to create a simple _Hello, World!_ action written as a Docker container.
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/>
## Contributing ## Contributing
We welcome contributions. See [how to contribute](.github/CONTRIBUTING.md). We welcome contributions! See [how to contribute](.github/CONTRIBUTING.md).
## Code of Conduct ## Code of Conduct