GitHub Actions Docker Build: Fixing Permission Denied on docker.sock

#Context

The error reads: permission denied while trying to connect to the Docker daemon socket at unix:///var/run/docker.sock. It means the process running the step cannot open the DockerThe KBY LexiconDockerDocker packages an application and its dependencies into a portable, isolated container using OS-level virtualisation, distinct from full virtual machines. Read Full Context daemon socket. The documented general causes are that the user lacks access to the socket, or that no daemon is reachable from where the step runs. The fix depends on where the job executes: a GitHub-hosted runner, a container job or a self-hosted runner. On a self-hosted runner, the usual fix is to grant the runner service user access to the daemon, restart the service, and accept that this access is root-equivalent on that host. Runner image contents and container job behaviour are documented in the GitHub Actions documentation.

Docker failures in a pipeline fall into three distinct classes that are often confused because they all surface as a failed build step. A socket permission fault is a local operating system access problem. A registry authentication fault is an identity and scope problem that appears at push or pull time. A caching problem is a performance problem, not a correctness problem. Treating them separately keeps the diagnosis short and prevents widening access when the real fault is a missing login step.

Related reading: bin-packing CI jobs across runner fleets covers runner capacity and placement, and ephemeral preview environments shows a build-and-deploy pattern that depends on working image builds.

#

Assumptions

• You can read the workflow file and, for self-hosted runners, have shell access to the runner host.
• You are validating in a non-production repository on a non-production runner before changing a shared one.
• The runner host is LinuxThe KBY LexiconLinuxLinux is the open-source kernel underlying most server, container and cloud infrastructure; distinct from the distributions built around it. Read Full Context . Windows and macOSThe KBY LexiconmacOSmacOS is Apple's Unix-based operating system for Mac hardware, forming the platform layer beneath endpoint management, security enforcement and application lifecycle tooling. Read Full Context runners expose Docker differently and are out of scope here.

#Architecture

The Docker command line is only a client. It sends API requests to a daemon, and on Linux the default transport is a Unix domain socket at /var/run/docker.sock. That socket is a filesystem object with an owner, a group and mode bits, so ordinary file permission rules decide who may connect. By default the socket is owned by root with group docker, so a user needs either root or membership of that group. The error text is therefore an operating system permission result, not a GitHub Actions policy decision.

Three execution contexts change what the client can see.

On a GitHub-hosted runner, Docker is generally provided on the Linux virtual machine, so the socket is normally usable by the job user without extra setup. In a container job the step runs inside a container, so unless a client and the socket are provided inside it, the command either is missing or cannot reach a daemon. Self-hosted runners are the most common source of the permission error, because the runner application runs as a service user that an administrator created and that may never have been granted daemon access.

One consequence of this design deserves emphasis. Access to the daemon socket is not a narrow privilege. A client that can talk to the daemon can ask it to start containers with host filesystem mounts and elevated settings, so granting socket access is equivalent to granting root on that host. This shapes both the fix and the security posture covered below.

#Implementation

Work through the contexts in order, and change nothing until you know which one you are in.

1. Identify the context. Read the workflow runs-on value. A label such as an Ubuntu image name indicates a GitHub-hosted runner, while custom labels or self-hosted indicate your own host. Then check for a job-level container: key, because that moves the steps inside a container regardless of where the runner lives.
2. Capture the exact message. The wording distinguishes the fault. permission denied on the socket is an access problem. Cannot connect to the Docker daemon ... Is the docker daemon running? points to a stopped daemon or a missing socket. docker: command not found points to a missing client. unauthorized or denied: requested access to the resource is denied at push time points to registry authentication.
3. Self-hosted: inspect the service user. Find which user the runner service runs as, then check its groups and the socket ownership using the read-only commands below.
4. Container job: decide whether the host daemon is needed. Often a dedicated build action or a build step on a hosted runner is safer than mounting the host socket into a job container. If the job genuinely needs the daemon, provide it deliberately and understand that the container then has host-level reach.
5. Registry login. Authenticate in the workflow before pushing, using repository secrets rather than literal credentials, and grant the job only the permissions it needs. A login failure is not fixed by changing socket access.
6. Caching. Treat the build cache as an optimisation. A cache miss makes a build slower; it does not cause a permission error, so do not change access to chase a slow build.

Read-only diagnostic commands on the runner host:

1id runner
2ls -l /var/run/docker.sock
3docker version

Expected evidence: the socket is listed with owner root and group docker. The id output includes docker among the groups only if access has been granted. docker version prints both a Client and a Server section when access works. If access is missing, the Client section prints, followed by the same permission denied message as the failing job.

Substitute the real service account name for runner. If the account name is unknown, inspect the runner service definition on the host rather than guessing, because adding the wrong account widens access for no benefit.

The state-changing fix on a self-hosted runner is adding the service user to the docker group:

1sudo usermod -aG docker runner

Group membership is read when a process starts, so the running runner service keeps its old groups until it is restarted. Stop the runner service, start it again, and then repeat the diagnostic commands as that user. Do this on one non-production runner first, and take it out of rotation while you change it so no job is mid-flight during the restart. Do not use broad permission changes such as making the socket world-writable; that removes the boundary for every user on the host and is not a supportable fix.

#Validation

Success is observable at three levels, and each should pass before you declare the fault fixed.

1. Host level. id for the service user lists the docker group, and docker version run as that user prints a Server section and exits zero.
2. Job level. A minimal workflow in a non-production repository, targeting only the changed runner, runs docker info and exits zero. This proves the runner process, not only an interactive shell, holds the new group.
3. Pipeline level. The real build runs in the non-production repository. Confirm the image builds, and if the pipeline pushes, confirm the push succeeds with the intended credentials and that the resulting image is present in the registry.

Also validate negative cases. A repository that should not be able to use the runner must still be unable to target it, and a job on a different runner must be unaffected. If an interactive check passes but the job still fails, the usual explanation is that the service was not restarted after the group change, or that the job runs in a container that never received the socket.

#Failure modes

• Group change made but the error persists. The runner service was not restarted, so it keeps its old group list. Restart the service and retest at job level.
• Cannot connect to the daemon, with no permission wording. The daemon is stopped, or the job runs in a container without the socket. Check the daemon state on the host and the container: key in the workflow.
• Command not found. The step runs in a container image without a Docker client. Use an image that includes a client or move the build to a context that has one.
• Unauthorized on push. Registry login is missing, the secret is wrong, or the token lacks write scope. Fix the login step and the token scope; do not alter socket access.
• Slow rebuilds. The cache is not being restored or its key changes on every run. This is a performance fault only.
• Fix works on one runner but not another. Runners in a fleet were provisioned differently. Compare group membership and service configuration across hosts, and consider building the fix into the image or provisioning code rather than patching hosts by hand.

#Security

Docker socket access is equivalent to root on the host, and the security assessment should start there. A workflow that can reach the socket can start privileged containers, mount host paths and read anything the host holds, including credentials left by earlier jobs on a persistent runner. Treat the decision to grant it as a privilege decision, not a convenience setting.

• Prefer GitHub-hosted runners or ephemeral self-hosted runners, so that each job starts from a clean host and a compromised job does not persist.
• Do not share a self-hosted runner that has socket access with untrusted code, such as workflows triggered by pull requests from forks.
• Do not mount the socket into containers that run untrusted workloads.
• Keep registry credentials in repository or environment secrets, scoped to the minimum needed, and avoid printing them in logs.
• Record who approved the access change and why, so that it can be reviewed and reversed.

Residual risk remains even after a correct fix: the runner is still a high-value target. The aim is to limit which repositories can reach it and how long it lives. General operational guidance on safe deployment, automation and observability is described in the Microsoft Learn operational excellence design principles, and a gated release approach is covered in deterministic rollout gating for progressive delivery.

#Recovery

Treat the group change as a reversible change with a defined stop point. Stop and roll back if any of these occur: jobs from repositories that should not use the runner begin running on it, the runner fails to come back online after restart, or unexpected containers appear on the host.

1. Take the runner out of rotation so no new jobs are scheduled to it.
2. Remove the service user from the docker group.
3. Restart the runner service so the removal takes effect, then confirm with id that the group is gone.
4. Confirm that the original permission denied error returns for the validation workflow. This is a safe failure state: builds fail closed rather than run with unreviewed access.
5. Review the change, then decide whether to retry, move to ephemeral runners or use a hosted runner.

No images or data are removed by this rollback, so no backup is needed for the access change itself.

#Operational checks after a Docker access fix

Once the fix is in place, make it part of routine operation rather than a one-off repair.

• Confirm the runner shows as online and idle, and that the validation workflow still passes after the next host update or image rebuild.
• Confirm only the intended repositories can target the runner by reviewing runner group and repository access settings.
• Check the host for unexpected running containers after a job completes.
• Watch for a rise in failed Docker steps, and classify each by message as socket, daemon, client, authentication or cache, so repeat faults point to a provisioning gap.
• Capture the group membership step in provisioning code so a rebuilt runner does not reintroduce the original error.

The next safe decision depends on what you found. If broad socket access is not acceptable for the repositories involved, move those builds to GitHub-hosted or ephemeral runners rather than widening access on a persistent host. If the fault was authentication or caching, leave socket access unchanged and correct the workflow instead.