Composite Actions, JavaScript Actions, Docker Actions, and Custom Automation: Guided Hands-On Workflow

1. Disposable lab preflight

Create a throwaway repository named gha-custom-action-lab. The mandatory path uses GitHub-hosted ubuntu-24.04, one repository-local composite action and actions/checkout pinned to its verified v7.0.1 commit. It requires no secret, registry, package publication, cloud account, Docker push or organization setting.

Before execution, record the commit SHA containing the workflow and local action. Predict that the composite action runs on the caller job's Ubuntu runner, that valid inputs produce one non-sensitive output, and that an unsupported mode exits before the caller's subsequent step.

2. Repository layout

.github/
  actions/
    ch17-contract/
      action.yml
      README.md
  workflows/
    ch17-local-action.yml

Keeping repository-local actions under .github/actions makes ownership visible without polluting application source. The workflow must check out the repository before a ./.github/actions/... reference because the runner needs those files in its workspace.

3. Implement the composite action

# .github/actions/ch17-contract/action.yml
name: Chapter 17 contract
description: Validate a documented string contract and return a safe summary
author: Abolfazl Mohammadijoo
inputs:
  mode:
    description: "Enum string: strict or relaxed"
    required: true
  repeat:
    description: "Integer string: 1, 2, or 3"
    required: false
    default: "1"
outputs:
  summary:
    description: Non-sensitive normalized result
    value: ${{ steps.validate.outputs.summary }}
  contract_kind:
    description: Fixed contract classification
    value: ${{ steps.validate.outputs.contract_kind }}
runs:
  using: composite
  steps:
    - id: validate
      name: Validate caller data
      shell: bash
      env:
        MODE: ${{ inputs.mode }}
        REPEAT: ${{ inputs.repeat }}
      run: |
        set -euo pipefail
        case "$MODE" in
          strict|relaxed) ;;
          *) echo "unsupported mode" >&2; exit 64 ;;
        esac
        [[ "$REPEAT" =~ ^[1-3]$ ]] || {
          echo "repeat must be 1, 2, or 3" >&2
          exit 65
        }
        printf 'summary=mode-%s-repeat-%s
' "$MODE" "$REPEAT" >> "$GITHUB_OUTPUT"
        printf 'contract_kind=validated-string-contract
' >> "$GITHUB_OUTPUT"

The action never evaluates input as code. The case and regular expression implement the type-like contract that action.yml itself cannot express. Failure codes 64 and 65 distinguish two validation boundaries without leaking the rejected value.

4. Invoke the local action

# .github/workflows/ch17-local-action.yml
name: chapter17-local-action
on: workflow_dispatch
permissions: {}

jobs:
  contract:
    runs-on: ubuntu-24.04
    steps:
      - name: Record bounded run evidence
        shell: bash
        run: |
          echo "repo=$GITHUB_REPOSITORY"
          echo "sha=$GITHUB_SHA"
          echo "run=$GITHUB_RUN_ID attempt=$GITHUB_RUN_ATTEMPT"
          echo "runner_os=$RUNNER_OS arch=$RUNNER_ARCH"

      - name: Check out exact caller revision
        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1

      - id: contract
        name: Run local composite action
        uses: ./.github/actions/ch17-contract
        with:
          mode: strict
          repeat: '2'

      - name: Verify non-sensitive outputs
        shell: bash
        env:
          SUMMARY: ${{ steps.contract.outputs.summary }}
          KIND: ${{ steps.contract.outputs.contract_kind }}
        run: |
          test "$SUMMARY" = "mode-strict-repeat-2"
          test "$KIND" = "validated-string-contract"
          printf 'summary=%s
kind=%s
' "$SUMMARY" "$KIND"

Expected evidence is a successful run at the recorded SHA and one action step that returns the two fixed-format outputs. There is no artifact, cache or external target. The output is control data, so GITHUB_OUTPUT is the correct channel.

5. Deliberate failure and causal evidence

For a controlled negative test, change only mode: strict to mode: unsupported, commit that workflow revision and dispatch it. The checkout still succeeds. The action starts, reaches its validation boundary, emits the generic error unsupported mode and exits 64. The output-verification step does not run.

Preserve that run ID, attempt, source SHA and failing step before repairing the caller. Do not add continue-on-error merely to make the run green; the failure is the evidence.

6. Same public contract as a JavaScript action

If this logic grows into cross-platform parsing, API calls or structured data processing, a JavaScript action can provide a cleaner implementation. The metadata changes execution model while keeping public names stable.

# Design comparison only — not required for the mandatory lab
name: Chapter 17 JS contract
inputs:
  mode:
    description: "Enum string: strict or relaxed"
    required: true
outputs:
  summary:
    description: Non-sensitive normalized result
runs:
  using: node24
  main: dist/index.js

// src/index.js — source; release process bundles dependencies into dist/index.js
import * as core from '@actions/core'

const mode = core.getInput('mode', { required: true })
if (!['strict', 'relaxed'].includes(mode)) {
  core.setFailed('unsupported mode')
} else {
  core.setOutput('summary', `mode-${mode}`)
}

Do not ship source that requires the caller to run npm install. Commit the reviewed bundle produced by your release build and record its source commit. The bundled dist directory is part of the action release, not a cache.

7. Docker action constraints before choosing it

# Design comparison only
runs:
  using: docker
  image: Dockerfile
  args:
    - ${{ inputs.mode }}

The Docker form can package OS-level dependencies, but it is Linux-only and needs Docker on self-hosted runners. Inputs passed as args become process arguments rather than automatically typed values. The image build context, base image and Dockerfile become supply-chain dependencies. Do not publish or push an image merely to complete this chapter.

Use Docker when the environment itself is part of the action contract. Do not use it simply to avoid packaging JavaScript or writing a small composite action.

8. Move from local test to immutable repository reference

After the action is committed and reviewed, record its full 40-character commit SHA. A caller in another repository should pin that SHA. Keep a release tag such as v1.0.0 as the human mapping, not as the immutable execution identity.

# Replace OWNER/REPO and the SHA with the reviewed release commit.
- name: Use released Chapter 17 action
  uses: OWNER/REPO/.github/actions/ch17-contract@0123456789abcdef0123456789abcdef01234567
  with:
    mode: strict
    repeat: '2'

The hexadecimal value above is intentionally illustrative, not a real published action. In a real disposable repository, copy the exact commit SHA from Git and record the mapping v1.0.0 → <full SHA> in the evidence packet. Never silently substitute @main for convenience.

9. Challenge: choose the boundary, not the shortest YAML

You need to run the same three validation commands in twelve jobs, all on caller-selected runners, with no secret and no external side effect. Choose a composite action and justify it. Then change the requirement: the automation now needs two coordinated jobs on different runners. The correct abstraction becomes a reusable workflow, not a larger composite action.

10. Verification and cleanup

• Confirm valid run output exactly matches the expected summary.
• Confirm the broken run stops in the action validation step with exit 64.
• Confirm no input value is interpolated directly into shell source.
• Confirm the only external action is checkout pinned to its full v7.0.1 SHA.
• Record action metadata path and caller source SHA.
• Delete the throwaway repository after preserving non-sensitive evidence.

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.