Docker "RUN --mount=type=ssh" - "SSH agent not available" / "no ssh forwarded"

A RUN --mount=type=ssh needs an SSH agent forwarded into the build with --ssh. BuildKit reports the agent is not available because either --ssh was not passed or no agent is running on the runner.

What this error means

A build that clones a private repo over SSH fails on the RUN --mount=type=ssh step with SSH agent not available or a downstream Permission denied (publickey). The Dockerfile is correct; the SSH socket was never forwarded.

docker build output

ERROR: failed to solve: SSH agent not available; make sure to use
"docker build --ssh default" and have an ssh-agent running
# or the clone itself fails: git@github.com: Permission denied (publickey)

Common causes

No --ssh passed to the build

The mount forwards an agent socket only when --ssh default (or --ssh id=...) is on the build command. Without it, the mount has no agent to expose.

No ssh-agent running on the runner

Even with --ssh default, there must be a live agent holding the key. A fresh CI shell has no agent until you start one and add the deploy key.

build-push-action ssh input missing

With docker/build-push-action, the ssh: input must request default; omitting it means no socket is forwarded.

How to fix it

Start an agent, add the key, and forward it

Load the deploy key into an agent, then pass --ssh default to the build.

Terminal

eval "$(ssh-agent -s)"
ssh-add - <<< "$DEPLOY_KEY"
docker build --ssh default .

Forward SSH in build-push-action

Use the action’s ssh-agent setup, then request the default socket.

.github/workflows/build.yml

- uses: webfactory/ssh-agent@v0.9.0
  with:
    ssh-private-key: ${{ secrets.DEPLOY_KEY }}
- uses: docker/build-push-action@v6
  with:
    ssh: default

How to prevent it

Always pair RUN --mount=type=ssh with --ssh default and a running agent.
Load the deploy key into the agent before the build step.
Prefer SSH forwarding or build secrets over copying keys into the image.