How to Run a Smoke Test in a Container in GitHub Actions

An image can build cleanly and still fail to boot; a smoke test runs it and checks it actually serves traffic.

Build the image, run it detached, poll a health endpoint, and fail the job if it never comes up.

Steps

• Build the image with docker build.
• Run it detached with a published port.
• Poll the health endpoint with curl and a retry loop; fail if it never responds.

Workflow

name: Smoke Test
on: [pull_request]
jobs:
  smoke:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: docker build -t app:ci .
      - name: Run and probe
        run: |
          docker run -d --name app -p 8080:8080 app:ci
          for i in $(seq 1 15); do
            if curl -fsS http://localhost:8080/healthz; then exit 0; fi
            sleep 2
          done
          echo "::error::Container never became healthy"; docker logs app; exit 1

Notes

• Dump docker logs on failure so the boot error is visible in the run.
• On Latchkey managed runners container smoke tests run cheaper and self-heal if a runner dies.

Related guides