Composite Actions, JavaScript Actions, Docker Actions, and Custom Automation: Configuration, Design Patterns, and Trade-Offs

1. Start with the boundary: who owns the job?

If the caller must retain the runner, job permissions, services, matrix cell and surrounding steps, an action is usually the right reuse boundary. If the reusable component needs to own jobs, needs, matrices, runner selection or deployment gates, use a reusable workflow. This decision prevents “mega-actions” that secretly reimplement workflow orchestration.

2. Composite versus JavaScript versus Docker

None is universally “more secure.” Security depends on implementation, caller permissions, supply-chain identity and runtime assumptions. Docker isolation does not neutralize a write token or mounted workspace; a composite action is not harmless because it looks like YAML.

3. Local versus external ownership

A repository-local action can evolve in the same change as its caller. That is convenient for application-specific logic but couples release cadence to one repository. An external action lets many repositories share one reviewed implementation, but now caller trust includes another repository and its release process.

Current GitHub.com also supports same-repository $/ references in supported contexts, which resolve against the repository containing the file and do not use a mutable @ref. The mandatory lab keeps the established ./ path plus checkout because it makes workspace mechanics explicit and remains easy to understand; production architecture should verify platform compatibility before adopting newer reference forms.

4. Bundled dependencies versus runtime install

For JavaScript actions, installing npm dependencies at action execution time adds registry availability, resolution state and package mutation to every workflow run. The normal production pattern is to lock dependencies, build a bundle, review the generated dist artifact and commit that bundle with the action release.

For composites, avoid assuming a random package exists globally on the runner. Either constrain the supported runner/tool baseline or invoke a reviewed setup action/tool installation. For Docker actions, the image and its base-image digest become the dependency bundle; a mutable FROM ...:latest simply moves the version problem into Docker.

5. Tag/release versus immutable SHA

A semantic tag such as v1.2.0 is excellent for release communication. It can also move or be deleted. A commit SHA identifies immutable Git content. For privileged production callers, record both: release v1.2.0 maps to reviewed SHA X, and callers execute SHA X.

When a security update is required, publish a new release and new SHA; update callers through code review. Do not “fix” the old SHA by moving a tag and assume consumers who pinned immutably will change automatically.

6. Interface stability: expose intent, not implementation knobs

An action interface should describe caller intent: mode: strict, not twenty flags mirroring every internal command-line switch. Because action inputs are strings, validate domain constraints at the edge and return a clear failure before invoking expensive or privileged operations.

Outputs should be small non-sensitive control values. Files belong in the workspace or artifacts according to lifecycle; secrets do not belong in outputs, caches or generated release bundles.

7. Permissions belong to the caller contract

An action README should say “requires contents: read” or “requires issues: write” when applicable, but the workflow grants that permission. This separation keeps authority review at the orchestration layer. An action that silently assumes the default token has write access is brittle and unsafe.

8. Pre/post state and cleanup design

JavaScript actions can have pre, main and post scripts under the same Node runtime. Docker actions can have pre-entrypoint and post-entrypoint phases, but each phase runs in a new container. When cleanup needs information from setup/main, save only the necessary non-sensitive state and use the documented action state mechanism.

Cleanup should be idempotent and bounded. A post step that deletes “the latest resource” or blindly revokes a shared credential creates a recovery hazard. Exact temporary resource IDs should be created, recorded and removed by the same action instance.

9. Worked decision table

10. Cost, latency and maintainability

Composite startup is small but may repeat setup work. JavaScript startup is typically fast but requires runtime maintenance and bundled dependency updates. Docker can give the most controlled userspace but pays image build/pull cost. Measure the real critical path before optimizing; do not choose Docker because “containers are DevOps” or JavaScript because “it is faster” without 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.