Docker Workflow

Docker Workflow

Purpose

Own the checked-in Dockerfile, .dockerignore, Linux runtime assets, and OCI contract for a Swift service. On Gale-owned product repositories this is a definition-only local workflow: GitHub Actions exclusively builds Linux images, runs image smoke tests, publishes immutable identities, and supplies deployment artifacts.

When To Use

• Use this skill to author or diagnose Dockerfile stages, entrypoints, runtime libraries, resources, non-root execution, ports, and GitHub image jobs.
• Inspect GitHub Actions logs and artifacts for Linux failures. On the Mac, run native Swift checks and edit definitions only.
• Use cloud-deployment-skills:dockerized-service-release-deployment-workflow for the build-once, digest-recorded, environment-gated release contract.
• Do not offer Compose, Colima, Docker Desktop, Apple containers, a container machine, or a Linux VM for product development or image validation.
• Do not use this skill for ordinary route, model, persistence, or SwiftPM work.

Source Check

Use repo-local definitions and official sources before making container claims:

• Dockerfile reference
• Docker build best practices
• Docker multi-stage builds
• Swift Docker images
• GitHub Actions publishing Docker images

The Docker Compose reference is not part of the Gale-product path.

Single-Path Workflow

1. Inspect Package.swift, the executable target, Dockerfile, .dockerignore, runtime resources, port/binding, graceful shutdown, and the owning GitHub workflow.
2. Confirm native behavior first with the nearest package's swift build and swift test when the issue is not Linux-specific.
3. Use a named multi-stage Dockerfile: match the supported Swift/Linux builder, build release output, and copy only the executable, required resources, and runtime libraries into the final image.
4. Run as a non-root user where possible; set WORKDIR, entrypoint, port, file ownership, writable paths, and SIGTERM behavior explicitly.
5. Keep .dockerignore free of source-control state, native build output, secrets, editor state, and host-only artifacts.
6. In GitHub Actions, build once from a clean checkout, run the image smoke test there, publish it, resolve its registry digest, and record that digest in the release manifest. Never rebuild during deployment.
7. Use protected GitHub environments for live-test and production. Deploy the exact recorded digest, verify health, and retain the previous digest as the rollback identity.
8. Diagnose failures from the exact GitHub job, image digest, stage, instruction, executable, resource, architecture, port, or health check.

Inputs

• repository and service root
• executable target and runtime command
• Dockerfile and .dockerignore paths
• required runtime resources, port, environment names, and health signal
• GitHub image workflow, registry, and immutable artifact contract

Outputs

• Dockerfile/runtime definition and explicit runtime assets
• GitHub-only build, smoke-test, publish, and deployment ownership
• immutable digest identity, health evidence, and rollback identity
• focused Vapor, Hummingbird, persistence, or cloud-deployment handoff

Guards and Stop Conditions

• Do not execute or recommend local docker build, docker run, image inspection, Compose, Colima, container-machine, or VM commands for a Gale-owned product.
• Do not add or preserve Compose as a local dependency path; use native Homebrew services.
• Do not use a mutable tag as deployment identity or rebuild source in a deploy job.
• Do not put secrets in build arguments, environment layers, logs, definitions, or committed local configuration.
• Stop when the GitHub job cannot prove the final image digest, smoke test, or runtime asset set.

Fallbacks and Handoffs

• Use hummingbird-server-workflow or vapor-server-workflow for application lifecycle, binding, routes, and readiness behavior.
• Use persistence-workflow for schema, migrations, and native Homebrew-backed local dependencies.
• Use cloud-deployment-skills:dockerized-service-release-deployment-workflow for immutable GitHub release and deployment orchestration.
• For a provider such as Fly.io, hand over only after GitHub has produced and recorded the exact image identity.

Customization

This workflow has no alternate local/runtime mode. Repository-specific ports, entrypoints, resources, registries, and health signals stay in checked-in Dockerfile and GitHub workflow sources.

References

• Dockerfile reference
• Swift Docker images
• GitHub Actions publishing Docker images