Composite Actions, JavaScript Actions, Docker Actions, and Custom Automation: Diagnostics, Failure Modes, and Production Practices

1. Evidence-first diagnostic sequence

When an action fails, do not begin by changing YAML or rerunning. Preserve the run ID, attempt, source SHA, action reference, runner OS/arch, metadata and first failing log. Then walk the layers: caller event/revision → job permissions/runner → action identity → metadata/runtime → implementation/dependencies → outputs/files → external side effects. Repair the first proven mismatch.

2. Broken JavaScript packaging: source exists, dependency does not

A common failure occurs when action.yml points to src/index.js, the source imports @actions/core, but node_modules is neither shipped nor bundled. The runner is not a development checkout with your npm dependencies. The first failure will be module resolution, not a token or runner-capacity problem.

Error [ERR_MODULE_NOT_FOUND]: Cannot find package '@actions/core'
imported from /home/runner/work/_actions/example/action/<sha>/src/index.js

The repair is release packaging: lock dependencies, create a reviewed bundle such as dist/index.js, point runs.main there, and publish a new immutable action commit. Do not add npm install to every caller as a troubleshooting shortcut.

3. Hidden runner-global dependency

A composite action works on one hosted image because a CLI happens to be preinstalled, then fails on another OS or after an image update. Evidence should compare runner image/tool versions and the action's documented prerequisites. The fix is to make the dependency explicit—support a constrained runner baseline or install/setup the tool through a versioned mechanism.

4. Hidden permission requirement

An action that calls the Issues API may fail with 403/404 under permissions: {}. Do not change to write-all. Inspect the action documentation/source and API requirement, then grant only issues: write to the specific caller job if the side effect is intentional. If the action is supposed to be read-only, a write requirement is an implementation defect.

5. Unsafe untrusted input interpolation

# Broken: expression result becomes shell program text.
- shell: bash
  run: echo "processing ${{ inputs.name }}"

If the caller controls name, special shell syntax can alter execution. The repair is to place the expression into an environment variable and quote the variable as data.

- shell: bash
  env:
    NAME: ${{ inputs.name }}
  run: printf 'processing %s
' "$NAME"

For higher-risk operations, validate an allow-list or use a structured API rather than a shell.

6. Mutable tag without release provenance

Suppose two runs both say uses: vendor/action@v1 but behave differently a week apart. The workflow text is identical while the dependency identity moved. Capture the resolved action SHA from logs/metadata where available and compare release history. The production fix is a reviewed full SHA plus a release mapping.

7. Custom action that should have been a reusable workflow

If an action starts launching its own background services, simulating multiple independent jobs, or encoding deployment gates, the abstraction is fighting Actions itself. Move job-graph concerns to a reusable workflow and keep custom actions focused on step-level execution.

8. Docker-specific failure layers

A Docker action on Windows or macOS will not run because Docker container actions require Linux. A self-hosted Linux runner without Docker has a different failure. An executable entrypoint permission error differs again. Preserve the exact runner and daemon evidence before changing the image or runner label.

Do not fix a Dockerfile workspace-access problem by granting privileged host access. GitHub's Docker action model has specific constraints, including default-user expectations for GITHUB_WORKSPACE.

9. Intentionally broken checkpoint fragment

permissions: {}
jobs:
  validate:
    runs-on: ubuntu-24.04
    steps:
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1
      - uses: ./.github/actions/ch17-contract
        with:
          mode: unsupported
          repeat: '2'

The expected failure is exit 64 in the composite validation step. If the run instead fails before that—checkout failure, path-not-found, YAML validation—diagnose that earlier layer first. The intended repair is one caller value: mode: strict. Do not edit permissions, checkout SHA or action code when the action is correctly rejecting the caller input.

10. Recovery rule: smallest equivalent rerun

After preserving the first failure, commit the minimal repair and dispatch a new run. Keep the old run. A rerun of the old attempt would still use its old workflow/action revision in ways that can obscure what changed; a new source SHA makes the repair explicit and reviewable.

Knowledge check

Official references and version notes

• GitHub Docs — About custom actions — execution-model and portability comparison.
• GitHub Docs — Metadata syntax reference — current action.yml inputs, outputs and runs models.
• GitHub Docs — Create a composite action — composite steps and GITHUB_ACTION_PATH.
• GitHub Docs — Create a JavaScript action — JavaScript packaging and runtime model.
• GitHub Docs — Create a Docker container action — Docker metadata, inputs and outputs.
• GitHub Docs — Dockerfile support for Actions — workspace, USER, ENTRYPOINT and CMD constraints.
• GitHub Docs — Managing custom actions — release management and immutable SHA references.
• actions/toolkit — official JavaScript action helper packages.
• GitHub Changelog — Node 20 deprecation — current Node 24 migration/removal schedule.