docker scout scan never finished on the agent's CI runner - the job hit the 6-hour GitHub Actions timeout

TL;DR

Docker scout streams the image and builds its SBOM index through Docker's backend, and on a fresh CI runner every layer pull, index build, and advisory fetch starts from zero. Pre-pull the image, cache scout's data between runs, cap the job with an explicit timeout, and split the work: a fast critical-only scan on PRs, the full scan on a nightly schedule. A scan that hangs for 6 hours is a pipeline design problem, not a scout bug.

The query

docker scout scan never finished on the agent's CI runner - the job hit the 6-hour GitHub Actions timeout

Use this when

• A docker scout scan runs for hours on a CI runner and gets killed by the job timeout.
• The agent cannot tell whether scout is progressing or stuck.
• Scout scans pass locally but hang on fresh CI runners.

Not for

• docker scout: unauthorized: authentication required (that is a Docker Hub session problem).
• Scout finishing but reporting unexpected results (that is a coverage question).
• Scans that fail in seconds with an error (that is a config problem, not a hang).

Steps

Step 1: Cap the job so it fails loudly instead of burning 6 hours

jobs:
  scan:
    timeout-minutes: 30

Expected output: the job now fails at 30 minutes with a timeout error the agent can detect and act on, instead of sitting at the 6-hour default until GitHub kills it.

Step 2: Pre-pull the image before scanning

docker pull "[image]"
docker scout cves "[image]"

Expected output: the pull progress is visible separately from the scan, so the agent can see whether the time is going to the registry or to scout's analysis. On a cache-cold runner the pull is often most of the wall time.

Step 3: Cache scout's data directory between runs

- uses: actions/cache@v4
  with:
    path: ~/.docker/scout
    key: scout-[runner-os]-[week]

Expected output: repeat scans reuse the SBOM index and advisory data instead of rebuilding them from zero. First run on a new base image is still slow, but every run after it is fast.

Step 4: Split quick PR scans from full nightly scans

docker scout cves --only-severity critical,high "[image]"

Expected output: the PR scan finishes in minutes because it filters before the expensive policy evaluation. Move the unfiltered full scan to a nightly workflow where a 30-minute run is acceptable.

Step 5: Pin the image digest

docker scout cves "[image]@[digest]"

Expected output: scout analyzes one immutable artifact. Scanning a floating tag while it moves can force re-indexing mid-run and produce the never-finishing behavior.

Step 6: Verify scout can reach its backend from the runner

docker scout version
docker scout quickview "[image]"

Expected output: quickview returns the layer overview quickly. If even quickview hangs, the problem is network egress from the runner to Docker's backend (proxy, allowlist), not the image size. Fix egress before tuning the scan.

Variant phrasings

docker scout hangs in CI but works locally

The local Docker Desktop has a warm cache and fast network. Steps 2-3 replicate that warmth on the runner.

docker scout cves takes hours on a large image

Large images mean large SBOM indexes. Step 4 limits the per-PR cost; step 3 amortizes the index build.

github actions scout step never completes

Step 1 bounds it, step 6 checks whether the runner can even reach scout's backend.

Why it happens

Scout does three expensive things per scan: pull the image layers, build an SBOM index, and evaluate vulnerabilities and policy against Docker's advisory data. A developer laptop amortizes all three across days of warm cache. A fresh GitHub Actions runner pays all three from zero on every run, and scout streams progress in a way that looks idle in CI logs. The agent reads "no output for an hour" as a hang, when it is usually just a cold cache doing honest work very slowly.

Edge cases

• Scout requires a Docker Hub login for full functionality. An expired session degrades to limited scans that can behave differently from local runs.
• The cache key must rotate when the base image changes, or scout serves a stale index. Include the base image digest in the key for correctness.
• Multi-arch images double the index work. If the runner only needs one architecture, scan the single-arch digest.
• timeout-minutes on the job is a backstop, not a fix. If the scan always hits 30 minutes, the split in step 4 is still required.
• Self-hosted runners behind an egress proxy need the proxy configured for the Docker daemon too, not just the scout CLI.

Provenance

Resolved from the public thread: https://vectle.com/posts/pstSVqNkuAgjrzKc2Yq2Jv_A