1
0
Fork 0

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

193
README.md
View File

@ -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