Docker "RUN --mount=type=ssh: agent not available" in CI

By Kaveh Alemi·Latchkey

A RUN --mount=type=ssh step expects an SSH agent socket forwarded into the build. If you do not pass --ssh on the docker buildx build command - or the agent has no loaded keys - BuildKit has nothing to mount and the step fails with "agent not available".

What this error means

A build step that clones a private repo over SSH fails with RUN --mount=type=ssh ... agent not available, even though the Dockerfile mount looks correct.

ERROR: failed to solve: failed to mount type=ssh: SSH agent not available; make sure SSH agent is running, SSH_AUTH_SOCK is set, and an SSH key is loaded

Common causes

The build was invoked without --ssh

The Dockerfile mounts type=ssh but the build command did not forward an agent with --ssh default.

No SSH agent or no loaded key in CI

The runner never started ssh-agent or never ran ssh-add, so SSH_AUTH_SOCK points at nothing usable.

A non-default ssh id mismatch

The mount names an id that does not match the one passed on --ssh id=....

How to fix it

Forward the agent with --ssh

1. Start an agent and load the deploy key in the job.
2. Pass --ssh default so BuildKit can mount the socket.

eval "$(ssh-agent -s)"
ssh-add - <<< "${{ secrets.DEPLOY_KEY }}"
docker buildx build --ssh default -t myorg/app:ci .

Match the ssh id in Dockerfile and command

1. If you name an id in the mount, pass the same id on the command.
2. Use default on both sides when you only have one key.

# Dockerfile
RUN --mount=type=ssh,id=github \
    git clone git@github.com:myorg/private.git

# command
docker buildx build --ssh github=$SSH_AUTH_SOCK -t myorg/app:ci .

How to prevent it

• Always pair a type=ssh mount with --ssh on the build command.
• Verify ssh-add -l lists a key before building in CI.

Frequently asked questions

Related guides

References

• Docker documentation
• Docker build cache
• GitHub Actions documentation