fix docker gid

[gfrankliu]

Description

Those comments about docker gid is incorrect. Docker hasn't changed GID generation. It is always:

                        # make sure the "docker" system group exists for "docker.socket" to apply it as the group on "docker.sock"
                        if ! getent group docker > /dev/null 2>&1; then
                                addgroup --system docker
                        fi

This means if we pre-create docker group with the gid we want, docker package installation will honor it. Otherwise it will create the docker group using command addgroup --system docker which means it will pick the next available system gid in the system gid range as defined in /etc/adduser.conf file:

...
FIRST_SYSTEM_GID=100
LAST_SYSTEM_GID=999
...

Depending on how many system packages are already installed, the last available system gid could be different and non predictable. If we want a predictable docker gid, we need to pre-create it, eg: addgroup --system --gid 900 docker, before we install docker package.

We can then add the "runner" user with the same gid, eg: useradd -m -s /bin/bash -c runner -g docker --uid 1001 runner. This will make sure the runner user have access to /var/run/docker.sock

Platforms affected

• [ ] Azure DevOps
• [x] GitHub Actions - Standard Runners
• [x] GitHub Actions - Larger Runners

Runner images affected

• [x] Ubuntu 22.04
• [x] Ubuntu 24.04
• [ ] macOS 13
• [ ] macOS 13 Arm64
• [ ] macOS 14
• [ ] macOS 14 Arm64
• [ ] macOS 15
• [ ] macOS 15 Arm64
• [ ] Windows Server 2019
• [ ] Windows Server 2022
• [ ] Windows Server 2025

Image version and build link

n/a

Is it regression?

no

Expected behavior

predictable gid

Actual behavior

non-predictable gid

Repro steps

N/A

[RaviAkshintala]

Hi @gfrankliu Thank you for bringing this issue to our attention. We will look into this issue and will update you after investigating.


[Prabhatkumar59]

Hi @gfrankliu - Appreciate your patience! As per our observation, your explanation is right, Docker itself doesn’t assign a fixed GID, it uses the next available system GID when the docker group is created automatically. We recommend pre-creating the docker group with the desired GID before installing Docker.

[erik-bershel]

Hey @gfrankliu!

Please provide use-case description for better understanding. What specific use cases does the current system of assigning a GID to the docker group break, and how would fixing a specific, pre-known number positively impact the user experience? Just in case, I should clarify whether we are talking only about the docker group here, or should we take into account the runner user group also? 🙏

Regarding the comment and commit you mentioned - it does not contain an error and means exactly what it means. We applied the workaround/fix based on a previously existing incident, which also has some history of its appearance.

[gfrankliu]

The "runner" user should be created with its primary group in "docker. Let's say if we decide "docker" group should use gid 900 and "runner" user should use uid 2000 (I purposely picked a higher number because lower numbers aren't guaranteed to be available if other groups or users were created beforehand and already used the numbers) :

groupadd --system --gid 900 docker
useradd -m -s /bin/bash -c runner -g 900 -u 2000 runner

Here is the use case why fixed numbers are important:

Today github runner jobs.container doesn't have options to run the container as the host "runner" user, nor does it support pre-steps where you can get the uid/gid of the "runner" to pass to docker run. The workaround in https://github.com/actions/runner/issues/691 suggests to use another job to get the "runner" user uid/gid. But since each job runs in different runner, and if runner images don't have fixed uid/gid, we can't really use those from one runner to another runner since they may change across images.

[Prabhatkumar59]

Hi @gfrankliu - Thanks for your input! We’ll review this internally and assess whether we can incorporate fixed UID/GID for the docker group and runner user into the image, then we will update you.

[Prabhatkumar59]

Hi @gfrankliu - We're currently not planning to enforce it due to potential conflicts with other systems that may use the same GID. So, we recommend using the GID as a build variable and either:

• Assign it dynamically at the start of your build, or

• Rely on the fact that for a specific image version (e.g., ubuntu-22.04 or ubuntu-24.04), the GID is stable and unlikely to change between updates, since the image composition stays consistent. So, closing this issue for now. Thanks!