Skip to content

Commit 08141f5

Browse files
author
Ryan (hackercat)
authored
fix: update readme with more relevant/updated information (#630)
1 parent 7ae9916 commit 08141f5

File tree

2 files changed

+148
-23
lines changed

2 files changed

+148
-23
lines changed

‎IMAGES.md

+81
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,81 @@
1+
# List of Docker images for `act`
2+
3+
**Warning:** Below badges with size for each image are displaying size of **compressed image size in registry. After pulling the image, size can be drastically different due to Docker uncompressing the image layers.**
4+
5+
## Images based on [`buildpack-deps`][hub/_/buildpack-deps]
6+
7+
**Note 1: `node` images are based on Debian root filesystem, while it is extremely similar to Ubuntu, there might be some differences**
8+
9+
**Note 2: `node` `-slim` images don't have `python` installed, if you want to use actions or software that is depending on `python`, you need to specify image manually**
10+
11+
| Image | Size |
12+
| ----------------------------------------- | ------------------------------------------------------------- |
13+
| [`node:12.20.1-buster`][hub/_/node] | ![`buster-size`][hub/_/node/12.20.1-buster/size] |
14+
| [`node:12.20.1-buster-slim`][hub/_/node] | ![`micro-buster-size`][hub/_/node/12.20.1-buster-slim/size] |
15+
| [`node:12.20.1-stretch`][hub/_/node] | ![`stretch-size`][hub/_/node/12.20.1-stretch/size] |
16+
| [`node:12.20.1-stretch-slim`][hub/_/node] | ![`micro-stretch-size`][hub/_/node/12.20.1-stretch-slim/size] |
17+
18+
**Note: `catthehacker/ubuntu` images are based on Ubuntu root filesystem**
19+
20+
| Image | Size | GitHub Repository |
21+
| ----------------------------------------------------------- | -------------------------------------------------------- | ------------------------------------------------------------- |
22+
| [`catthehacker/ubuntu:act-latest`][hub/catthehacker/ubuntu] | ![`act-latest`][hub/catthehacker/ubuntu/act-latest/size] | [`catthehacker/docker-images`][gh/catthehacker/docker_images] |
23+
| [`catthehacker/ubuntu:act-20.04`][hub/catthehacker/ubuntu] | ![`act-20.04`][hub/catthehacker/ubuntu/act-20.04/size] | [`catthehacker/docker-images`][gh/catthehacker/docker_images] |
24+
| [`catthehacker/ubuntu:act-18.04`][hub/catthehacker/ubuntu] | ![`act-18.04`][hub/catthehacker/ubuntu/act-18.04/size] | [`catthehacker/docker-images`][gh/catthehacker/docker_images] |
25+
| [`catthehacker/ubuntu:act-16.04`][hub/catthehacker/ubuntu] | ![`act-16.04`][hub/catthehacker/ubuntu/act-16.04/size] | [`catthehacker/docker-images`][gh/catthehacker/docker_images] |
26+
27+
## Images based on [`actions/virtual-environments`][gh/actions/virtual-environments]
28+
29+
**Note: `nektos/act-environments-ubuntu` have been last updated in February, 2020. It's recommended to update the image manually after `docker pull` if you decide to to use it.**
30+
31+
| Image | Size | GitHub Repository |
32+
| --------------------------------------------------------------------------------- | -------------------------------------------------------------------------- | ------------------------------------------------------- |
33+
| [`nektos/act-environments-ubuntu:18.04`][hub/nektos/act-environments-ubuntu] | ![`nektos:18.04`][hub/nektos/act-environments-ubuntu/18.04/size] | [`nektos/act-environments`][gh/nektos/act-environments] |
34+
| [`nektos/act-environments-ubuntu:18.04-lite`][hub/nektos/act-environments-ubuntu] | ![`nektos:18.04-lite`][hub/nektos/act-environments-ubuntu/18.04-lite/size] | [`nektos/act-environments`][gh/nektos/act-environments] |
35+
| [`nektos/act-environments-ubuntu:18.04-full`][hub/nektos/act-environments-ubuntu] | ![`nektos:18.04-full`][hub/nektos/act-environments-ubuntu/18.04-full/size] | [`nektos/act-environments`][gh/nektos/act-environments] |
36+
37+
| Image | Size | GitHub Repository |
38+
| ----------------------------------------------------------- | -------------------------------------------------------- | ------------------------------------------------------------- |
39+
| [`catthehacker/ubuntu:full-20.04`][hub/catthehacker/ubuntu] | ![`full-20.04`][hub/catthehacker/ubuntu/full-20.04/size] | [`catthehacker/docker-images`][gh/catthehacker/docker_images] |
40+
41+
## Other images
42+
43+
| Image | Size | GitHub Repository |
44+
| ---------------------------------------------------- | ------------------------------------------------- | ------------------------------------------------------------- |
45+
| [`catthehacker/alpine:act`][hub/catthehacker/alpine] | ![`alpine:act`][hub/catthehacker/alpine/act/size] | [`catthehacker/docker-images`][gh/catthehacker/docker_images] |
46+
47+
Feel free to make a pull request with your image added here
48+
49+
[hub/_/buildpack-deps]: https://hub.docker.com/_/buildpack-deps
50+
[hub/_/node]: https://hub.docker.com/r/_/node
51+
[hub/_/node/12.20.1-buster/size]: https://img.shields.io/docker/image-size/_/node/12.20.1-buster
52+
[hub/_/node/12.20.1-buster-slim/size]: https://img.shields.io/docker/image-size/_/node/12.20.1-buster-slim
53+
[hub/_/node/12.20.1-stretch/size]: https://img.shields.io/docker/image-size/_/node/12.20.1-stretch
54+
[hub/_/node/12.20.1-stretch-slim/size]: https://img.shields.io/docker/image-size/_/node/12.20.1-stretch-slim
55+
[hub/catthehacker/ubuntu]: https://hub.docker.com/r/catthehacker/ubuntu
56+
[hub/catthehacker/ubuntu/act-latest/size]: https://img.shields.io/docker/image-size/catthehacker/ubuntu/act-latest
57+
[hub/catthehacker/ubuntu/act-20.04/size]: https://img.shields.io/docker/image-size/catthehacker/ubuntu/act-20.04
58+
[hub/catthehacker/ubuntu/act-18.04/size]: https://img.shields.io/docker/image-size/catthehacker/ubuntu/act-18.04
59+
[hub/catthehacker/ubuntu/act-16.04/size]: https://img.shields.io/docker/image-size/catthehacker/ubuntu/act-16.04
60+
[hub/catthehacker/ubuntu/full-20.04/size]: https://img.shields.io/docker/image-size/catthehacker/ubuntu/full-20.04
61+
[hub/nektos/act-environments-ubuntu]: https://hub.docker.com/r/nektos/act-environments-ubuntu
62+
[hub/nektos/act-environments-ubuntu/18.04/size]: https://img.shields.io/docker/image-size/nektos/act-environments-ubuntu/18.04
63+
[hub/nektos/act-environments-ubuntu/18.04-lite/size]: https://img.shields.io/docker/image-size/nektos/act-environments-ubuntu/18.04-lite
64+
[hub/nektos/act-environments-ubuntu/18.04-full/size]: https://img.shields.io/docker/image-size/nektos/act-environments-ubuntu/18.04-full
65+
66+
<!-- Other images links -->
67+
68+
[hub/catthehacker/alpine]: https://hub.docker.com/r/catthehacker/alpine
69+
[hub/catthehacker/alpine/act/size]: https://img.shields.io/docker/image-size/catthehacker/alpine/act
70+
71+
<!--
72+
[hub/<username>/<image>]: https://hub.docker.com/r/[username]/[image]
73+
[hub/<username>/<image>/<tag>/size]: https://img.shields.io/docker/image-size/[username]/[image]/[tag]
74+
-->
75+
76+
<!-- GitHub repository links -->
77+
78+
[gh/nektos/act-environments]: https://github.com/nektos/act-environments
79+
[gh/actions/virtual-environments]: https://github.com/actions/virtual-environments
80+
[gh/catthehacker/docker_images]: https://github.com/catthehacker/docker_images
81+
[gh/catthehacker/virtual-environments]: https://github.com/catthehacker/virtual-environments

‎README.md

+67-23
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
![](https://github.com/nektos/act/wiki/img/logo-150.png)
22

3-
# Overview [![push](https://github.com/nektos/act/workflows/push/badge.svg?branch=master&event=push)](https://github.com/nektos/act/actions) [![Join the chat at https://gitter.im/nektos/act](https://badges.gitter.im/nektos/act.svg)](https://gitter.im/nektos/act?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge) [![Go Report Card](https://goreportcard.com/badge/github.com/nektos/act)](https://goreportcard.com/report/github.com/nektos/act)[![awesome-runners](https://img.shields.io/badge/listed%20on-awesome--runners-blue.svg)](https://github.com/jonico/awesome-runners)
3+
# Overview [![push](https://github.com/nektos/act/workflows/push/badge.svg?branch=master&event=push)](https://github.com/nektos/act/actions) [![Join the chat at https://gitter.im/nektos/act](https://badges.gitter.im/nektos/act.svg)](https://gitter.im/nektos/act?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge) [![Go Report Card](https://goreportcard.com/badge/github.com/nektos/act)](https://goreportcard.com/report/github.com/nektos/act) [![awesome-runners](https://img.shields.io/badge/listed%20on-awesome--runners-blue.svg)](https://github.com/jonico/awesome-runners)
44

55

66
> "Think globally, `act` locally"
@@ -20,34 +20,66 @@ Let's see it in action with a [sample repo](https://github.com/cplee/github-acti
2020

2121
# Installation
2222

23+
## Necessary prerequisites for running `act`
24+
`act` depends on `docker` to run workflows.
25+
26+
If you are using macOS, please be sure to follow the steps outlined in [Docker Docs for how to install Docker Desktop for Mac](https://docs.docker.com/docker-for-mac/install/).
27+
28+
If you are using Windows, please follow steps for [installing Docker Desktop on Windows](https://docs.docker.com/docker-for-windows/install/).
29+
30+
If you are using Linux, you will need to [install Docker Engine](https://docs.docker.com/engine/install/).
31+
32+
`act` is currently not supported with `podman` or other container backends (it might work, but it's not guaranteed). Please see [#303](https://github.com/nektos/act/issues/303) for updates.
33+
34+
## Homebrew
35+
2336
To install with [Homebrew](https://brew.sh/), run:
2437

25-
`brew install act`
38+
```shell
39+
brew install act
40+
```
2641

2742
Alternatively, you can use the following:
2843

29-
`curl https://raw.githubusercontent.com/nektos/act/master/install.sh | sudo bash`
30-
31-
NOTE: Currently not compatible with Apple Silicon (ARM). This project relies on Docker which has not been ported to Apple Silicon yet.
44+
```shell
45+
curl https://raw.githubusercontent.com/nektos/act/master/install.sh | sudo bash
46+
```
3247

3348
If you are running Windows, download the [latest release](https://github.com/nektos/act/releases/latest) and add the binary into your PATH.
3449
If you are using [Chocolatey](https://chocolatey.org/) then run:
35-
`choco install act-cli`
50+
51+
[![](https://img.shields.io/chocolatey/v/act-cli)](https://community.chocolatey.org/packages/act-cli)
52+
```shell
53+
choco install act-cli
54+
```
3655

3756
If you are using [Scoop](https://scoop.sh/) then run:
38-
`scoop install act`
57+
58+
[![](https://img.shields.io/scoop/v/act)](https://github.com/ScoopInstaller/Main/blob/master/bucket/act.json)
59+
60+
```shell
61+
scoop install act
62+
```
3963

4064
If you are running Arch Linux, you can install the [act](https://aur.archlinux.org/packages/act/) package with your favorite package manager:
4165

42-
`yay -S act`
66+
[![](https://img.shields.io/aur/version/act)](https://aur.archlinux.org/packages/act/)
67+
68+
```shell
69+
yay -S act
70+
```
4371

4472
If you are using NixOS or the Nix package manager on another platform you can install act globally by running
4573

46-
`nix-env -iA nixpkgs.act`
74+
```sh
75+
nix-env -iA nixpkgs.act
76+
```
4777

4878
or in a shell by running
4979

50-
`nix-shell -p act`
80+
```sh
81+
nix-shell -p act
82+
```
5183

5284
# Commands
5385

@@ -117,6 +149,8 @@ It will save that information to `~/.actrc`, please refer to [Configuration](#co
117149

118150
# Known Issues
119151

152+
## `MODULE_NOT_FOUND`
153+
120154
A `MODULE_NOT_FOUND` during `docker cp` command [#228](https://github.com/nektos/act/issues/228) can happen if you are relying on local changes that have not been pushed. This can get triggered if the action is using a path, like:
121155

122156
```yaml
@@ -137,42 +171,53 @@ steps:
137171

138172
If the `path:` value doesn't match the name of the repository, a `MODULE_NOT_FOUND` will be thrown.
139173

174+
## `act` on Windows
175+
176+
Running `act` on Windows host is currently broken - see [#587](https://github.com/nektos/act/issues/587)
177+
140178
# Runners
141179

142180
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:
143181

144-
| GitHub Runner | Micro Docker Image | Medium Docker Image | Large Docker Image |
145-
| ------------- | ---------------------------------- | ---------------------------------------- | --------------------------------------------- |
146-
| ubuntu-latest | [node:12.20.1-buster-slim][micro] | [catthehacker/ubuntu:act-latest][medium] | `unavailable` |
147-
| ubuntu-20.04 | [node:12.20.1-buster-slim][micro] | [catthehacker/ubuntu:act-20.04][medium] | `unavailable` |
148-
| ubuntu-18.04 | [node:12.20.1-buster-slim][micro] | [catthehacker/ubuntu:act-18.04][medium] | [nektos/act-environments-ubuntu:18.04][large] |
149-
| ubuntu-16.04 | [node:12.20.1-stretch-slim][micro] | [catthehacker/ubuntu:act-16.04][medium] | `unavailable` |
182+
| GitHub Runner | Micro Docker Image | Medium Docker Image | Large Docker Image |
183+
| --------------- | ------------------------------------ | ------------------------------------------ | ------------------------------------------------------ |
184+
| `ubuntu-latest` | [`node:12.20.1-buster-slim`][micro] | [`catthehacker/ubuntu:act-latest`][medium] | [`catthehacker/ubuntu:full-20.04`][large-cat] |
185+
| `ubuntu-20.04` | [`node:12.20.1-buster-slim`][micro] | [`catthehacker/ubuntu:act-20.04`][medium] | [`catthehacker/ubuntu:full-20.04`][large-cat] |
186+
| `ubuntu-18.04` | [`node:12.20.1-buster-slim`][micro] | [`catthehacker/ubuntu:act-18.04`][medium] | [`nektos/act-environments-ubuntu:18.04`][large-act] |
187+
| `ubuntu-16.04` | [`node:12.20.1-stretch-slim`][micro] | [`catthehacker/ubuntu:act-16.04`][medium] | `unavailable` |
188+
189+
[micro]: https://hub.docker.com/_/buildpack-deps
190+
[medium]: https://github.com/catthehacker/docker_images
191+
[large-cat]: https://github.com/catthehacker/act-environments
192+
[large-act]: https://github.com/nektos/act-environments
150193

151-
Below platforms are currently **unsupported and won't work** (see issue [#97])
194+
Below platforms are currently **unsupported and won't work** (see issue [#97](https://github.com/nektos/act/issues/97))
152195

153196
- `windows-latest`
154197
- `windows-2019`
155198
- `macos-latest`
156199
- `macos-10.15`
157200

158-
[micro]: https://hub.docker.com/_/buildpack-deps
159-
[medium]: https://github.com/catthehacker/docker_images
160-
[large]: https://github.com/nektos/act-environments
161-
[#97]: https://github.com/nektos/act/issues/97
201+
## Please see [IMAGES.md](./IMAGES.md) for more information about the Docker images that can be used with `act`
162202

163203
## Default runners are intentionally incomplete
164204

165205
These default images do **not** contain **all** the tools that GitHub Actions offers by default in their runners.
166206
Many things can work improperly or not at all while running those image.
207+
Additionally, some software might still not work even if installed properly, since GitHub Actions are running in fully virtualized machines while `act` is using Docker containers (e.g. Docker does not support running `systemd`).
208+
In case of any problems [please create issue](https://github.com/nektos/act/issues/new/choose) in respective repository (issues with `act` in this repository, issues with `nektos/act-environments-ubuntu:18.04` in [`nektos/act-environments`](https://github.com/nektos/act-environments) and issues with any image from user `catthehacker` in [`catthehacker/docker_images`](https://github.com/catthehacker/docker_images))
167209

168210
## Alternative runner images
169211

170212
If you need an environment that works just like the corresponding GitHub runner then consider using an image provided by [nektos/act-environments](https://github.com/nektos/act-environments):
171213

172-
- [nektos/act-environments-ubuntu:18.04](https://hub.docker.com/r/nektos/act-environments-ubuntu/tags) - built from the Packer file GitHub uses in [actions/virtual-environments](https://github.com/actions/runner).
214+
- [`nektos/act-environments-ubuntu:18.04`](https://hub.docker.com/r/nektos/act-environments-ubuntu/tags) - built from the Packer file GitHub uses in [actions/virtual-environments](https://github.com/actions/runner).
173215

174216
:warning: :elephant: `*** WARNING - this image is >18GB 😱***`
175217

218+
- [`catthehacker/ubuntu:full-20.04`](https://hub.docker.com/r/catthehacker/ubuntu/tags) - built from Dockerfile based on the Packer template from [actions/virtual-environments](https://github.com/actions/runner).
219+
This image size is about `61GB` unpacked (`23GB` compressed) but contains more recent software versions (as of date of build).
220+
176221
## Use an alternative runner image
177222

178223
To use a different image for the runner, use the `-P` option.
@@ -272,6 +317,5 @@ Want to contribute to act? Awesome! Check out the [contributing guidelines](CONT
272317

273318
- Install Go tools 1.16+ - (https://golang.org/doc/install)
274319
- Clone this repo `git clone [email protected]:nektos/act.git`
275-
- Pull the default docker image `docker pull nektos/act-environments-ubuntu:18.04`
276320
- Run unit tests with `make test`
277321
- Build and install: `make install`

0 commit comments

Comments
 (0)