Run Command

Escape hatch: run any shell command in any container image.

Reference: loha/run-command@v1

Category: test

Runtime: alpine:3.19 (non-root, digest-pinned)

License: Apache-2.0

When to use

Use this step when nothing else fits. Database migrations, custom validation scripts, asset compilation, vendored CLI tools: anything that doesn't deserve its own purpose-built step. Prefer the specialized tasks (run-lint, run-tests, type-check) when they apply, since they capture better metrics.

Parameters

Parameter	Type	Default	Required	Description
COMMAND	string	—	Yes	The shell command to execute. Can be a single command or multi-line script.
WORKING_DIRECTORY	string	.	No	Directory to run in, relative to workspace root. Use for monorepo subdirectories.
IMAGE	string	alpine@sha256:6baf43584bcb78f2e5847d1de515f23499913ac9f12bdf834811a3145eb11ca1	No	Container image to use. Default is alpine:3.19. Specify custom images for specific tools.
SHELL	enum: sh, bash, ash	sh	No	Shell interpreter to use. Options: sh, bash, ash. Default is sh.
FAIL_ON_ERROR	enum: true, false	true	No	Fail the step if the command returns a non-zero exit code. Set to false for optional checks.

Workspaces

• source (required): bound from pipeline workspace source

Results

Result	Description
EXIT_CODE	Command exit code (0 = success)
OUTPUT_PATH	Path to command output log file

How it works

Spins up IMAGE (default alpine:3.19), cds into WORKING_DIRECTORY, and pipes COMMAND into the configured SHELL. The exit code is exposed as EXIT_CODE; the full output is written to OUTPUT_PATH for later inspection. Runs as a non-root user (UID 1000).

Examples

One-line script

steps:
  - name: validate-config
    uses: loha/run-command@v1
    with:
      COMMAND: 'python scripts/validate-config.py'

Multi-line bash with strict mode

steps:
  - name: setup-database
    uses: loha/run-command@v1
    with:
      SHELL: 'bash'
      COMMAND: |
        set -euo pipefail
        echo "Running migrations..."
        npm run db:migrate
        npm run db:seed

Custom image with a vendored tool

steps:
  - name: terraform-validate
    uses: loha/run-command@v1
    with:
      COMMAND: 'terraform validate'
      IMAGE: 'hashicorp/terraform:1.6'

Optional check (do not fail the pipeline)

steps:
  - name: optional-benchmark
    uses: loha/run-command@v1
    with:
      COMMAND: 'npm run benchmark'
      FAIL_ON_ERROR: 'false'

Troubleshooting

Problem: command not found for a tool you expected to be available.

Solution: The default alpine:3.19 image is intentionally minimal. Either pass an IMAGE that ships with the tool, or install it in your command (apk add --no-cache curl && curl ...).

---

Problem: Multi-line script exits early on first error you did not expect.

Solution: Add set -e (or set -euo pipefail for stricter mode) at the top of your script; sh's default is to keep going on errors.

---

Problem: Permission denied writing files.

Solution: The step runs as UID 1000. If your command needs to write into a path created by an earlier step running as root, fix the upstream step rather than escalating here.