Actions Runner Container Name "runner"

[baoalvin1]

Why are you starting this discussion?

Question

What GitHub Actions topic or product is this about?

Actions Runner Image

Discussion Details

Hi! I was wondering why the ARC and Actions Runner Image requires the EphemeralRunnerContainerName to be runner?

I ended up patching ARC to remove this assumption but when I try to run the actual runner image it seems like /home/runner/.runner doesn't exist on the host, is there an assumption somewhere that doesn't copy over the configuration files if the container is not named runner?

[daudibrahimhasan]

You're trying to understand why this naming convention is required and whether it's safe to modify it — especially since changing the name seems to cause problems, such as:

"/home/runner/.runner doesn't exist on the host"

🔍 GitHub Actions Context

In ARC, when using ephemeral runners, the pod typically consists of:

A main runner container, usually named runner

Optionally, sidecars like DinD (Docker-in-Docker)

Shared volumes for configuration and data

The container named runner is assumed to be the one that actually:

Executes the GitHub Actions runner binary

Uses /home/runner as the work directory

Writes registration metadata in .runner (e.g. config, tokens, etc.)

📌 Why the runner Container Name Matters

This is likely due to a hardcoded assumption in:

ARC's logic that mounts volumes, sets up environment, or copies secrets

The Actions Runner Docker image entrypoint, which may:

Expect config paths in fixed locations

Possibly mount a shared volume under /home/runner

Interact with other containers or the host based on that name

For example:

ARC might create a shared volume and mount it only into a container named runner

If you change the container name (e.g. custom-runner), the mount or config copy step may not happen

As a result, the .runner directory is never created → breaking the runner startup

🧪 Your Observation

"I ended up patching ARC to remove this assumption"

That’s a valid exploration — but unless you also update the runner image, or ARC's controller logic responsible for volume mounting, your patch might not be enough.

✅ Recommendations

Stick to runner unless you want to fork and fully maintain the ARC + runner image logic.

If you must change the container name:

Carefully audit the ARC source (especially the runnerpod.go and ephemeral_runner.go)

Ensure that:

Volumes like /home/runner are correctly mounted

Config files (e.g. .runner) are copied/created

The entrypoint scripts inside the runner image don’t assume the container name

Open an issue or discussion in the ARC GitHub repo
if you think this should be configurable.

[ashmeet07]

You've hit a core, non-configurable design point in the Actions Runner Controller (ARC) and the associated runner image. The requirement for the container name to be runner is based on hardcoded assumptions within the system.

Why the Container Name Must Be runner

The name runner is a fundamental assumption used in the orchestration logic:

1. ARC Controller Logic: The ARC component (especially files like runnerpod.go and ephemeral_runner.go) specifically expects the main container—the one executing the runner binary—to be named runner. This name is used to determine which container in the Kubernetes Pod should receive configuration, environment variables, and crucial Volume Mounts.
2. Configuration Path: The runner application expects its configuration and registration files (like .runner) to reside in a specific location, typically /home/runner/. The ARC controller often creates a shared volume for this purpose and explicitly mounts it to the container named runner.
3. Your Observation: Your finding that /home/runner/.runner is missing when you change the container name confirms that the ARC controller is failing to mount the volume or copy the necessary setup files into your custom-named container because its logic is looking for the container named runner.

Recommendation

Since you are patching ARC, that's a valid path for deep customization, but to make a name change work:

• Stick to runner: The simplest solution is to adhere to the default runner name, as maintaining a fully patched fork of ARC and potentially the runner image is significant overhead.
• Audit and Patch ARC Completely: If you must change it, you need to fully audit the ARC source to ensure every place where the container name is used for volume mounting, environment injection, or status checking is updated to look for your custom name. This is a non-trivial undertaking.