Update README.md/cmd/root.go with additional information (#523)
* Update README * Add notice about large image, add link to repo for `.actrc`
This commit is contained in:
Cat™
GitHub
parent
ec6b1624c0
commit
fc46f506e3
2 changed files with 53 additions and 26 deletions
77
README.md
77
README.md
|
|
@ -2,7 +2,7 @@
|
|||
|
||||
# Overview [](https://github.com/nektos/act/actions) [](https://gitter.im/nektos/act?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge) [](https://goreportcard.com/report/github.com/nektos/act)
|
||||
|
||||
> "Think globally, <code>act</code> locally"
|
||||
> "Think globally, `act` locally"
|
||||
|
||||
Run your [GitHub Actions](https://developer.github.com/actions/) locally! Why would you want to do this? Two reasons:
|
||||
|
||||
|
|
@ -29,11 +29,11 @@ Alternatively, you can use the following:
|
|||
|
||||
NOTE: Currently not compatible with Apple Silicon (ARM). This project relies on Docker which has not been ported to Apple Silicon yet.
|
||||
|
||||
If you are running Windows, download the [latest release](https://github.com/nektos/act/releases/latest) and add the binary into your PATH.
|
||||
If you are using [Chocolatey](https://chocolatey.org/) then run:
|
||||
If you are running Windows, download the [latest release](https://github.com/nektos/act/releases/latest) and add the binary into your PATH.
|
||||
If you are using [Chocolatey](https://chocolatey.org/) then run:
|
||||
`choco install act-cli`
|
||||
|
||||
If you are using [Scoop](https://scoop.sh/) then run:
|
||||
If you are using [Scoop](https://scoop.sh/) then run:
|
||||
`scoop install act`
|
||||
|
||||
If you are running Arch Linux, you can install the [act](https://aur.archlinux.org/packages/act/) package with your favorite package manager:
|
||||
|
|
@ -50,7 +50,7 @@ or in a shell by running
|
|||
|
||||
# Commands
|
||||
|
||||
```
|
||||
```sh
|
||||
# Command structure:
|
||||
act [<event>] [options]
|
||||
If no event name passed, will default to "on: push"
|
||||
|
|
@ -77,9 +77,14 @@ act -n
|
|||
act -v
|
||||
```
|
||||
|
||||
## First `act` run
|
||||
|
||||
When running `act` for the first time, it will ask you to choose image to be used as default.
|
||||
It will save that information to `~/.actrc`, please refer to [Configuration](#configuration) for more information about `.actrc` and to [Runners](#runners) for information about used/available Docker images.
|
||||
|
||||
# Flags
|
||||
|
||||
```
|
||||
```none
|
||||
-a, --actor string user that triggered the event (default "nektos/act")
|
||||
-b, --bind bind working directory to container, rather than copy
|
||||
--defaultbranch string the name of the main branch
|
||||
|
|
@ -110,7 +115,7 @@ act -v
|
|||
|
||||
MODULE_NOT_FOUND during `docker cp` command [#228](https://github.com/nektos/act/issues/228)
|
||||
|
||||
```
|
||||
```yaml
|
||||
steps:
|
||||
- name: Checkout
|
||||
uses: actions/checkout@v2
|
||||
|
|
@ -120,22 +125,31 @@ steps:
|
|||
|
||||
# Runners
|
||||
|
||||
GitHub Actions offers managed [virtual environments](https://help.github.com/en/actions/reference/virtual-environments-for-github-hosted-runners) for running workflows. In order for `act` to run your workflows locally, it must run a container for the runner defined in your workflow file. Here are the images that `act` uses for each runner type:
|
||||
GitHub Actions offers managed [virtual environments](https://help.github.com/en/actions/reference/virtual-environments-for-github-hosted-runners) for running workflows. In order for `act` to run your workflows locally, it must run a container for the runner defined in your workflow file. Here are the images that `act` uses for each runner type and size:
|
||||
|
||||
| GitHub Runner | Docker Image |
|
||||
| -------------- | ----------------------------------------------------------------- |
|
||||
| ubuntu-latest | [node:12.6-buster-slim](https://hub.docker.com/_/buildpack-deps) |
|
||||
| ubuntu-20.04 | [node:12.6-buster-slim](https://hub.docker.com/_/buildpack-deps) |
|
||||
| ubuntu-18.04 | [node:12.6-buster-slim](https://hub.docker.com/_/buildpack-deps) |
|
||||
| ubuntu-16.04 | [node:12.6-stretch-slim](https://hub.docker.com/_/buildpack-deps) |
|
||||
| windows-latest | `unsupported` |
|
||||
| windows-2019 | `unsupported` |
|
||||
| macos-latest | `unsupported` |
|
||||
| macos-10.15 | `unsupported` |
|
||||
| GitHub Runner | Micro Docker Image | Medium Docker Image | Large Docker Image |
|
||||
| -------------- | ------------------------------- | ---------------------------------------- | --------------------------------------------- |
|
||||
| ubuntu-latest | [node:12.6-buster-slim][micro] | [catthehacker/ubuntu:act-latest][medium] | [nektos/act-environments-ubuntu:18.04][large] |
|
||||
| ubuntu-20.04 | [node:12.6-buster-slim][micro] | [catthehacker/ubuntu:act-20.04][medium] | `unavailable` |
|
||||
| ubuntu-18.04 | [node:12.6-buster-slim][micro] | [catthehacker/ubuntu:act-18.04][medium] | [nektos/act-environments-ubuntu:18.04][large] |
|
||||
| ubuntu-16.04 | [node:12.6-stretch-slim][micro] | [catthehacker/ubuntu:act-16.04][medium] | `unavailable` |
|
||||
|
||||
Below platforms are currently **unsupported and won't work** (see issue [#97])
|
||||
|
||||
- `windows-latest`
|
||||
- `windows-2019`
|
||||
- `macos-latest`
|
||||
- `macos-10.15`
|
||||
|
||||
[micro]: https://hub.docker.com/_/buildpack-deps
|
||||
[medium]: https://github.com/catthehacker/docker_images
|
||||
[large]: https://github.com/nektos/act-environments
|
||||
[#97]: https://github.com/nektos/act/issue/97
|
||||
|
||||
## Default runners are intentionally incomplete
|
||||
|
||||
These default images do **not** contain **all** the tools that GitHub Actions offers by default in their runners.
|
||||
Many things can work improperly or not at all while running those image.
|
||||
|
||||
## Alternative runner images
|
||||
|
||||
|
|
@ -147,12 +161,25 @@ If you need an environment that works just like the corresponding GitHub runner
|
|||
|
||||
## Use an alternative runner image
|
||||
|
||||
To use a different image for the runner, use the `-P` option:
|
||||
To use a different image for the runner, use the `-P` option.
|
||||
|
||||
```sh
|
||||
act -P <platform>=<docker-image>
|
||||
```
|
||||
|
||||
If your workflow uses `ubuntu-18.04`, consider below line as an example for changing Docker image used to run that workflow:
|
||||
|
||||
```sh
|
||||
act -P ubuntu-18.04=nektos/act-environments-ubuntu:18.04
|
||||
```
|
||||
|
||||
If you use multiple platforms in your workflow, you have to specify them to change which image is used.
|
||||
For example, if your workflow uses `ubuntu-18.04`, `ubuntu-16.04` and `ubuntu-latest`, specify all platforms like below
|
||||
|
||||
```sh
|
||||
act -P ubuntu-18.04=nektos/act-environments-ubuntu:18.04 -P ubuntu-latest=ubuntu:latest -P ubuntu-16.04=node:12.6-buster-slim
|
||||
```
|
||||
|
||||
# Secrets
|
||||
|
||||
To run `act` with secrets, you can enter them interactively, supply them as environment variables or load them from a file. The following options are available for providing secrets:
|
||||
|
|
@ -166,20 +193,20 @@ To run `act` with secrets, you can enter them interactively, supply them as envi
|
|||
|
||||
You can provide default configuration flags to `act` by either creating a `./.actrc` or a `~/.actrc` file. Any flags in the files will be applied before any flags provided directly on the command line. For example, a file like below will always use the `nektos/act-environments-ubuntu:18.04` image for the `ubuntu-latest` runner:
|
||||
|
||||
```
|
||||
```sh
|
||||
# sample .actrc file
|
||||
-P ubuntu-18.04=nektos/act-environments-ubuntu:18.04
|
||||
-P ubuntu-latest=nektos/act-environments-ubuntu:18.04
|
||||
```
|
||||
|
||||
Additionally, act supports loading environment variables from an `.env` file. The default is to look in the working directory for the file but can be overridden by:
|
||||
|
||||
```
|
||||
```sh
|
||||
act --env-file my.env
|
||||
```
|
||||
|
||||
`.env`:
|
||||
|
||||
```
|
||||
```env
|
||||
MY_ENV_VAR=MY_ENV_VAR_VALUE
|
||||
MY_2ND_ENV_VAR="my 2nd env var value"
|
||||
```
|
||||
|
|
@ -200,7 +227,7 @@ don't want to run locally. E.g. a step that posts a Slack message or bumps a ver
|
|||
|
||||
Every [GitHub event](https://developer.github.com/v3/activity/events/types) is accompanied by a payload. You can provide these events in JSON format with the `--eventpath` to simulate specific GitHub events kicking off an action. For example:
|
||||
|
||||
```pull-request.json
|
||||
```json
|
||||
{
|
||||
"pull_request": {
|
||||
"head": {
|
||||
|
|
@ -213,7 +240,7 @@ Every [GitHub event](https://developer.github.com/v3/activity/events/types) is a
|
|||
}
|
||||
```
|
||||
|
||||
```
|
||||
```sh
|
||||
act -e pull-request.json
|
||||
```
|
||||
|
||||
|
|
|
|||
|
|
@ -202,7 +202,7 @@ func newRunCommand(ctx context.Context, input *Input) func(*cobra.Command, []str
|
|||
if os.IsNotExist(err) {
|
||||
var answer string
|
||||
confirmation := &survey.Select{
|
||||
Message: "Please choose the default image you want to use with act:\n\n - Large size image: +20GB Docker image, includes almost all tools used on GitHub Actions\n - Medium size image: ~500MB, includes only necessary tools to bootstrap actions and aims to be compatible with all actions\n - Micro size image: <200MB, contains only NodeJS required to bootstrap actions, doesn't work with all actions\n\nDefault image and other options can be changed manually in ~/.actrc",
|
||||
Message: "Please choose the default image you want to use with act:\n\n - Large size image: +20GB Docker image, includes almost all tools used on GitHub Actions (only ubuntu-latest/ubuntu-18.04 platform is available)\n - Medium size image: ~500MB, includes only necessary tools to bootstrap actions and aims to be compatible with all actions\n - Micro size image: <200MB, contains only NodeJS required to bootstrap actions, doesn't work with all actions\n\nDefault image and other options can be changed manually in ~/.actrc (please refer to https://github.com/nektos/act#configuration for additional information about file structure)",
|
||||
Help: "If you want to know why act asks you that, please go to https://github.com/nektos/act/issues/107",
|
||||
Default: "Medium",
|
||||
Options: []string{"Large", "Medium", "Micro"},
|
||||
|
|
|
|||
Loading…
Reference in a new issue