diff --git a/IMAGES.md b/IMAGES.md new file mode 100644 index 0000000..aff78cf --- /dev/null +++ b/IMAGES.md @@ -0,0 +1,81 @@ +# List of Docker images for `act` + +**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.** + +## Images based on [`buildpack-deps`][hub/_/buildpack-deps] + +**Note 1: `node` images are based on Debian root filesystem, while it is extremely similar to Ubuntu, there might be some differences** + +**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** + +| Image | Size | +| ----------------------------------------- | ------------------------------------------------------------- | +| [`node:12.20.1-buster`][hub/_/node] | ![`buster-size`][hub/_/node/12.20.1-buster/size] | +| [`node:12.20.1-buster-slim`][hub/_/node] | ![`micro-buster-size`][hub/_/node/12.20.1-buster-slim/size] | +| [`node:12.20.1-stretch`][hub/_/node] | ![`stretch-size`][hub/_/node/12.20.1-stretch/size] | +| [`node:12.20.1-stretch-slim`][hub/_/node] | ![`micro-stretch-size`][hub/_/node/12.20.1-stretch-slim/size] | + +**Note: `catthehacker/ubuntu` images are based on Ubuntu root filesystem** + +| Image | Size | GitHub Repository | +| ----------------------------------------------------------- | -------------------------------------------------------- | ------------------------------------------------------------- | +| [`catthehacker/ubuntu:act-latest`][hub/catthehacker/ubuntu] | ![`act-latest`][hub/catthehacker/ubuntu/act-latest/size] | [`catthehacker/docker-images`][gh/catthehacker/docker_images] | +| [`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] | +| [`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] | +| [`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] | + +## Images based on [`actions/virtual-environments`][gh/actions/virtual-environments] + +**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.** + +| Image | Size | GitHub Repository | +| --------------------------------------------------------------------------------- | -------------------------------------------------------------------------- | ------------------------------------------------------- | +| [`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] | +| [`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] | +| [`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] | + +| Image | Size | GitHub Repository | +| ----------------------------------------------------------- | -------------------------------------------------------- | ------------------------------------------------------------- | +| [`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] | + +## Other images + +| Image | Size | GitHub Repository | +| ---------------------------------------------------- | ------------------------------------------------- | ------------------------------------------------------------- | +| [`catthehacker/alpine:act`][hub/catthehacker/alpine] | ![`alpine:act`][hub/catthehacker/alpine/act/size] | [`catthehacker/docker-images`][gh/catthehacker/docker_images] | + +Feel free to make a pull request with your image added here + +[hub/_/buildpack-deps]: https://hub.docker.com/_/buildpack-deps +[hub/_/node]: https://hub.docker.com/r/_/node +[hub/_/node/12.20.1-buster/size]: https://img.shields.io/docker/image-size/_/node/12.20.1-buster +[hub/_/node/12.20.1-buster-slim/size]: https://img.shields.io/docker/image-size/_/node/12.20.1-buster-slim +[hub/_/node/12.20.1-stretch/size]: https://img.shields.io/docker/image-size/_/node/12.20.1-stretch +[hub/_/node/12.20.1-stretch-slim/size]: https://img.shields.io/docker/image-size/_/node/12.20.1-stretch-slim +[hub/catthehacker/ubuntu]: https://hub.docker.com/r/catthehacker/ubuntu +[hub/catthehacker/ubuntu/act-latest/size]: https://img.shields.io/docker/image-size/catthehacker/ubuntu/act-latest +[hub/catthehacker/ubuntu/act-20.04/size]: https://img.shields.io/docker/image-size/catthehacker/ubuntu/act-20.04 +[hub/catthehacker/ubuntu/act-18.04/size]: https://img.shields.io/docker/image-size/catthehacker/ubuntu/act-18.04 +[hub/catthehacker/ubuntu/act-16.04/size]: https://img.shields.io/docker/image-size/catthehacker/ubuntu/act-16.04 +[hub/catthehacker/ubuntu/full-20.04/size]: https://img.shields.io/docker/image-size/catthehacker/ubuntu/full-20.04 +[hub/nektos/act-environments-ubuntu]: https://hub.docker.com/r/nektos/act-environments-ubuntu +[hub/nektos/act-environments-ubuntu/18.04/size]: https://img.shields.io/docker/image-size/nektos/act-environments-ubuntu/18.04 +[hub/nektos/act-environments-ubuntu/18.04-lite/size]: https://img.shields.io/docker/image-size/nektos/act-environments-ubuntu/18.04-lite +[hub/nektos/act-environments-ubuntu/18.04-full/size]: https://img.shields.io/docker/image-size/nektos/act-environments-ubuntu/18.04-full + + + +[hub/catthehacker/alpine]: https://hub.docker.com/r/catthehacker/alpine +[hub/catthehacker/alpine/act/size]: https://img.shields.io/docker/image-size/catthehacker/alpine/act + + + + + +[gh/nektos/act-environments]: https://github.com/nektos/act-environments +[gh/actions/virtual-environments]: https://github.com/actions/virtual-environments +[gh/catthehacker/docker_images]: https://github.com/catthehacker/docker_images +[gh/catthehacker/virtual-environments]: https://github.com/catthehacker/virtual-environments diff --git a/README.md b/README.md index 5994ff3..72ca97a 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ ![](https://github.com/nektos/act/wiki/img/logo-150.png) -# 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) +# 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) > "Think globally, `act` locally" @@ -20,34 +20,66 @@ Let's see it in action with a [sample repo](https://github.com/cplee/github-acti # Installation +## Necessary prerequisites for running `act` +`act` depends on `docker` to run workflows. + +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/). + +If you are using Windows, please follow steps for [installing Docker Desktop on Windows](https://docs.docker.com/docker-for-windows/install/). + +If you are using Linux, you will need to [install Docker Engine](https://docs.docker.com/engine/install/). + +`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. + +## Homebrew + To install with [Homebrew](https://brew.sh/), run: -`brew install act` +```shell +brew install act +``` Alternatively, you can use the following: -`curl https://raw.githubusercontent.com/nektos/act/master/install.sh | sudo bash` - -NOTE: Currently not compatible with Apple Silicon (ARM). This project relies on Docker which has not been ported to Apple Silicon yet. +```shell +curl https://raw.githubusercontent.com/nektos/act/master/install.sh | sudo bash +``` 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` + +[![](https://img.shields.io/chocolatey/v/act-cli)](https://community.chocolatey.org/packages/act-cli) +```shell +choco install act-cli +``` If you are using [Scoop](https://scoop.sh/) then run: -`scoop install act` + +[![](https://img.shields.io/scoop/v/act)](https://github.com/ScoopInstaller/Main/blob/master/bucket/act.json) + +```shell +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: -`yay -S act` +[![](https://img.shields.io/aur/version/act)](https://aur.archlinux.org/packages/act/) + +```shell +yay -S act +``` If you are using NixOS or the Nix package manager on another platform you can install act globally by running -`nix-env -iA nixpkgs.act` +```sh +nix-env -iA nixpkgs.act +``` or in a shell by running -`nix-shell -p act` +```sh +nix-shell -p act +``` # Commands @@ -117,6 +149,8 @@ It will save that information to `~/.actrc`, please refer to [Configuration](#co # Known Issues +## `MODULE_NOT_FOUND` + 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: ```yaml @@ -137,42 +171,53 @@ steps: If the `path:` value doesn't match the name of the repository, a `MODULE_NOT_FOUND` will be thrown. +## `act` on Windows + +Running `act` on Windows host is currently broken - see [#587](https://github.com/nektos/act/issues/587) + # 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 and size: -| GitHub Runner | Micro Docker Image | Medium Docker Image | Large Docker Image | -| ------------- | ---------------------------------- | ---------------------------------------- | --------------------------------------------- | -| ubuntu-latest | [node:12.20.1-buster-slim][micro] | [catthehacker/ubuntu:act-latest][medium] | `unavailable` | -| ubuntu-20.04 | [node:12.20.1-buster-slim][micro] | [catthehacker/ubuntu:act-20.04][medium] | `unavailable` | -| ubuntu-18.04 | [node:12.20.1-buster-slim][micro] | [catthehacker/ubuntu:act-18.04][medium] | [nektos/act-environments-ubuntu:18.04][large] | -| ubuntu-16.04 | [node:12.20.1-stretch-slim][micro] | [catthehacker/ubuntu:act-16.04][medium] | `unavailable` | +| GitHub Runner | Micro Docker Image | Medium Docker Image | Large Docker Image | +| --------------- | ------------------------------------ | ------------------------------------------ | ------------------------------------------------------ | +| `ubuntu-latest` | [`node:12.20.1-buster-slim`][micro] | [`catthehacker/ubuntu:act-latest`][medium] | [`catthehacker/ubuntu:full-20.04`][large-cat] | +| `ubuntu-20.04` | [`node:12.20.1-buster-slim`][micro] | [`catthehacker/ubuntu:act-20.04`][medium] | [`catthehacker/ubuntu:full-20.04`][large-cat] | +| `ubuntu-18.04` | [`node:12.20.1-buster-slim`][micro] | [`catthehacker/ubuntu:act-18.04`][medium] | [`nektos/act-environments-ubuntu:18.04`][large-act] | +| `ubuntu-16.04` | [`node:12.20.1-stretch-slim`][micro] | [`catthehacker/ubuntu:act-16.04`][medium] | `unavailable` | -Below platforms are currently **unsupported and won't work** (see issue [#97]) +[micro]: https://hub.docker.com/_/buildpack-deps +[medium]: https://github.com/catthehacker/docker_images +[large-cat]: https://github.com/catthehacker/act-environments +[large-act]: https://github.com/nektos/act-environments + +Below platforms are currently **unsupported and won't work** (see issue [#97](https://github.com/nektos/act/issues/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/issues/97 +## Please see [IMAGES.md](./IMAGES.md) for more information about the Docker images that can be used with `act` ## 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. +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`). +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)) ## Alternative runner images 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): -- [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). +- [`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). :warning: :elephant: `*** WARNING - this image is >18GB 😱***` +- [`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). +This image size is about `61GB` unpacked (`23GB` compressed) but contains more recent software versions (as of date of build). + ## Use an alternative runner image 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 - Install Go tools 1.16+ - (https://golang.org/doc/install) - Clone this repo `git clone git@github.com:nektos/act.git` -- Pull the default docker image `docker pull nektos/act-environments-ubuntu:18.04` - Run unit tests with `make test` - Build and install: `make install`