/ 
App-Actions-0.001.0
/ action-run-smoke

NAME

action-run-smoke - check that Docker can run an App::Actions workflow

SYNOPSIS

action-run-smoke [options]

Check this computer, with the defaults:

action-run-smoke

Check the drive your projects are on, and show the Docker commands:

action-run-smoke --directory ~/src --verbose

On an ARM computer, test x86 images:

action-run-smoke --platform linux/amd64

Also test an image that only a step can name:

action-run-smoke --scenario deferred

DESCRIPTION

In short: run this once after you install App::Actions, or after you change Docker. It checks that Docker works, and then runs a tiny workflow for real. If it says "ready" and the workflow passes, action-run will work on this computer.

action-run-smoke is the end-to-end check to run after installing App::Actions or after changing Docker, a virtual machine, or a drive's sharing settings. It does what action-run check does and then one more thing: it runs a small workflow against the real daemon.

The environment part reports the host platform, the Docker client and daemon versions, whether the daemon runs Linux containers, and whether Docker can bind-mount a temporary directory and the given directory.

The image part then prepares the images the smoke workflow needs, without repeating the probes: it pulls what is missing and prints one line per image naming the job, service or action that needs it and whether it was pulled, already there, failed, skipped or deferred. A deferred image is one whose name only a step can supply; its expression and the reason it could not be resolved are printed, and the step prepares it when the workflow runs. An image that cannot be prepared stops the smoke test before the workflow starts, so a mistyped image or a registry login problem is reported here rather than halfway through a job.

The workflow part starts one container from the image, runs four steps in it, and checks that a variable written to GITHUB_ENV and an output written to GITHUB_OUTPUT by one step are seen by the next, and that the container is Linux. Those are the two things the fake Docker used by the test suite cannot really prove.

--scenario deferred runs a second, opt-in workflow whose action image is decided by a step. The preflight cannot name that image, so it reports it as deferred with the expression it could not resolve; the step then prepares the image it chose and runs it. The scenario fails rather than passing quietly if the deferred image was not reported as deferred, since proving that report is the whole point of it.

The temporary project is removed afterwards, along with the containers, networks and images the run created.

OPTIONS

--docker command

The Docker command. The default is $ENV{DOCKER} or docker. A wrapper script is used as given; a wrapper written in Perl is run with the current interpreter, which is what makes it usable on Windows.

--image image

The Linux image used for the mount probe and the smoke workflow. The default is alpine:3.20.

--platform platform

Pass --platform to Docker, for example linux/amd64 on an ARM host that emulates x86 images.

--scenario name

The workflow to run. smoke, the default, runs one job with four steps that check GITHUB_ENV, GITHUB_OUTPUT and the container. deferred runs an image that only a step can name: the preflight reports it as deferred rather than guessing, and the step prepares it when the workflow runs. It is opt-in because it needs an extra image, hello-world:latest, and because a deferral is the one part of the image preparation that the plain scenario never reaches.

--directory directory

The directory mounted read-only during the mount check, and reported at the top of the output. It defaults to the current directory. Use a directory on the drive where workflows live, so that a drive Docker Desktop has not shared is caught here rather than in the middle of a run.

--verbose, -v

Show the Docker commands that the smoke workflow runs.

--help, -h

Show this help.

--version, -V

Show the version.

EXIT STATUS

0 when the environment is ready, its images are prepared and the smoke workflow succeeded, 1 when the environment is ready but the workflow failed, and 2 when the environment or an image it needs has to be fixed before a workflow can run.

EXAMPLES

action-run-smoke

action-run-smoke --directory C:\src\project

action-run-smoke --scenario deferred

On Windows, with Docker Desktop:

C:\> action-run-smoke
C:\> action-run-smoke --directory C:\src\project --verbose

Both require Docker Desktop to be running with the WSL 2 Linux engine, so that docker info --format "{{.OSType}}" reports linux. If the report says the daemon runs windows containers, switch Docker Desktop to Linux containers from its tray icon. If the mount check fails, share the drive in Settings > Resources > File sharing. Point --docker at another executable when Docker is not on PATH:

C:\> action-run-smoke --docker "C:\Program Files\Docker\Docker\resources\bin\docker.exe"

COMMON PITFALLS

  • It downloads images. The first run pulls alpine:3.20 (and hello-world:latest with --scenario deferred). It removes the images it pulled when it finishes.

  • Docker must run Linux containers. On Windows, switch Docker Desktop to Linux containers first.

  • --directory must be on the drive you use. The default is the current directory, which may be on a drive Docker can see even if your projects are not.

  • The image needs a shell and the usual tools (sh, cat, ls, wc). A "distroless" image will fail.

  • Exit status 1 and 2 mean different things. 2: fix the computer or Docker (the report says how). 1: Docker is ready, but the workflow failed; run again with --verbose to see why.

ENCODING

The report is ASCII, apart from folder names and Docker's own output, which are shown as bytes. The --directory path may contain any characters your system allows, including non-ASCII characters and emoji. The smoke workflow itself is ASCII.

AUTHOR

Nigel Horne, njh@nigelhorne.com

STATE DIAGRAM

What one run of action-run-smoke does:

 action-run-smoke [options]
        |
        v
+---------------------+  bad option -> usage; exit 2
| PARSE OPTIONS       |  --help / --version -> print; exit 0
+---------------------+
        |
        v
+---------------------+  Docker missing, not running, Windows
| ENVIRONMENT CHECK   |  containers, mount fails
| (as action-run      |  -> report with remedies; exit 2
|  check)             |
+---------------------+
        |
        v
+---------------------+  one line per image: pulled / present /
| PREPARE IMAGES      |  failed / skipped / deferred
|                     |  an image fails -> exit 2
+---------------------+
        |
        v
+---------------------+  smoke: 4 steps check GITHUB_ENV,
| RUN THE WORKFLOW    |  GITHUB_OUTPUT and that it is Linux
| in a temporary      |  deferred: the step names its image; it
| project             |  must have been reported as deferred
+---------------------+
        |
        v
+---------------------+  temporary project, containers, networks
| CLEAN UP            |  and pulled images removed
+---------------------+
        |
        v
  exit 0 = ready and passed, 1 = ready but the workflow failed

LICENSE AND COPYRIGHT

Copyright 2026 Nigel Horne.

This program is released under the GNU General Public License, version 2. See the LICENSE file that comes with this distribution. If you use it, please let me know.