GitHub Actions Runner

Prerequisites

• An active Azure subscription, an SSH public key, and a VNet with a subnet in the target region
• A subscription to the GitHub Actions Runner listing on Azure Marketplace
• A network security group (NSG) rule that allows TCP 22 for administration. No inbound CI port is required, because the runner connects outbound to GitHub
• Admin rights on the GitHub repository, organisation or enterprise that you want to register the runner to, so that you can generate a registration token
• Outbound HTTPS (TCP 443) egress to github.com and its Actions endpoints

Recommended virtual machine size: Standard_D4s_v5 (4 vCPU, 16 GB RAM). A runner that does real work, such as compiling code, running test suites and building container images, is much more demanding than an idle appliance. Burstable B-series credits are the wrong shape for sustained build load. Scale up or out from there according to your job mix.

Troubleshooting

The service will not start. If systemctl start github-actions-runner appears to do nothing and the unit stays inactive, the runner is not registered yet. The unit is gated on /opt/actions-runner/.runner, which config.sh creates. Complete Step 7 first. Run systemctl status github-actions-runner to check, because it reports a skipped start condition.

config.sh refuses to run. Run it as the service account with sudo -u ghrunner, not as root. The runner deliberately refuses to configure as root.

The runner does not appear in GitHub. Registration tokens expire within the hour. Generate a fresh token and retry. Confirm that the VM has outbound HTTPS egress to github.com.

Container jobs fail. Confirm that docker.service is active and that the runner account is in the docker group, using id ghrunner. Group membership applies to the service on start, so restart the runner service after any change.

Check what the image contains. Run sudo /opt/actions-runner/runner-selftest.sh at any time to repeat every image-level check, including the credential sweeps.

Support

SecureAnyCloud provides 24/7 technical support for this GitHub Actions Runner image. Our engineers help with registration, runner groups and labels, scaling to a fleet, workflow and caching design, container and service container jobs, hardening the execution environment for untrusted code, network and firewall rules, and runner version upgrades. Critical issues receive a one-hour average response time. Contact sales@secureanycloud.com.

All product and company names are trademarks or registered trademarks of their respective holders. Use of these names does not imply any affiliation with or endorsement by them.

Deploy on Azure

Launch GitHub Actions Runner 2.335.1 on Ubuntu 24.04 LTS on Azure with 24/7 support from SecureAnyCloud.

View this image

Need Help?

Our support team is available 24/7.

sales@secureanycloud.com

Prerequisites

Before you deploy this image, you need:

• An Amazon Web Services account where you can launch EC2 instances
• IAM permissions to launch instances, create security groups and subscribe to AWS Marketplace products
• An SSH key pair in the Region you intend to launch in
• A GitHub account with permission to add a self-hosted runner to the repository, organisation or enterprise you intend to serve. Adding a runner to a repository requires admin on that repository. Adding one to an organisation requires organisation owner

Launching the instance

You can launch from the AWS Marketplace console or from the AWS CLI.

To launch from the console, subscribe to the product and choose Launch through EC2. Pick your instance type and key pair, and select a security group that allows inbound TCP 22 from your own management address only. No other inbound port is required.

To launch from the CLI, substitute the AMI ID shown on the product page, your key name, your subnet and your security group:

aws ec2 run-instances \
  --image-id ami-EXAMPLE0000000000 \
  --instance-type m5.large \
  --key-name your-key-name \
  --security-group-ids sg-EXAMPLE00000000 \
  --subnet-id subnet-EXAMPLE00000 \
  --tag-specifications 'ResourceType=instance,Tags=[{Key=Name,Value=actions-runner}]'

Choosing an instance type

The listing recommends m5.large (2 vCPU, 8 GiB), which is a sensible general-purpose starting size and is available in every commercial region.

Size the instance to your workload, not to the idle runner. An idle runner uses almost no CPU, but a runner that does real work compiles code, runs test suites and builds container images. If your builds are heavy, move up to m5.xlarge or m5.2xlarge. Alternatively, run several smaller runners in parallel and let GitHub distribute jobs across them.

Give / enough room for your build working set. The runner's _work directory holds a full checkout plus build artefacts for every job.

Connecting to your instance

Connect over SSH on port 22 with the key pair that you selected at launch. The login user depends on the operating system variant that you launched:

OS variant SSH login user

Ubuntu 24.04 LTS ubuntu

ssh -i /path/to/your-key.pem ubuntu@<public-ip>

After you connect, read the per-instance runner identity and the registration instructions written for this instance:

sudo cat /root/github-actions-runner-credentials.txt

The file is written on first boot with mode 0600 root:root. It contains no secret, because this image has no secret to hold. It records this instance's generated runner name, the work directory, the service account, the runner version and the reachable address, and it records runner.registered=false.

To confirm that the identity was written and that only root can read the file, run the following command. It does not print the file:

echo "identity keys written by first boot:"
sudo grep -E '^runner\.(name|work_dir|service_user|version|registered)=' /root/github-actions-runner-credentials.txt
PERMS=$(sudo stat -c '%a %U:%G' /root/github-actions-runner-credentials.txt)
echo "permissions: ${PERMS}" if [ "${PERMS}" = "600 root:root" ]; then
echo "OK: instructions file is root only" else
echo "UNEXPECTED permissions: ${PERMS}" exit 1 fi

What is preinstalled

Every package below is present because a real workflow needs it. Each one is listed here because a build image that quietly accumulates packages is a liability rather than a convenience.

Component Why it is here

actions/runner 2.335.1 The official self-hosted runner agent, installed at /opt/actions-runner from the pinned, checksum-verified upstream release

git Every workflow starts with actions/checkout

docker.io Container jobs and service containers, the single most common self-hosted runner requirement. The ghrunner account is in the docker group

build-essential, make, pkg-config Compiled projects

python3, python3-pip, python3-venv Python tooling and virtual environments

jq JSON handling in workflow steps

rsync, zip, unzip, tar, gzip Artefact packing and transfer

curl, wget, ca-certificates, gnupg, openssl Fetching and verifying dependencies

iproute2 Network diagnostics

Docker is installed from the Ubuntu archive rather than from Docker's own repository. It therefore stays inside the distribution's security update stream, which is the stream that this image is patched against and that the AWS Marketplace CVE scan measures.

Verifying the image

These checks are read-only and safe to run at any time.

Confirm the runner agent is installed and reports its real version:

sudo -u ghrunner /opt/actions-runner/bin/Runner.Listener --version

Confirm that the first-boot unit ran and Docker is up:

FB=$(systemctl is-enabled github-actions-runner-firstboot.service 2>/dev/null || true)
DK=$(systemctl is-active docker.service 2>/dev/null || true)
echo "firstboot unit: ${FB}"
echo "docker.service: ${DK}" if [ "${FB}" = "enabled" ] && [ "${DK}" = "active" ]; then
echo "OK: first boot initialisation is enabled and Docker is running" else
echo "UNEXPECTED: firstboot=${FB} docker=${DK}" exit 1 fi

Confirm the runner service ships installed but disabled, which is the correct state before you register:

STATE=$(systemctl is-enabled github-actions-runner.service 2>/dev/null || true)
ACTIVE=$(systemctl is-active github-actions-runner.service 2>/dev/null || true)
echo "github-actions-runner.service is-enabled: ${STATE}"
echo "github-actions-runner.service is-active: ${ACTIVE}" if [ "${STATE}" = "disabled" ] && [ "${ACTIVE}" != "active" ]; then
echo "OK: the runner is installed and waiting for you to register it" else
echo "UNEXPECTED state: enabled=${STATE} active=${ACTIVE}" exit 1 fi

The built-in self-test

The image ships a self-test that checks, on your own instance, everything that can be verified about a runner that is deliberately not yet registered. It confirms that:

• The agent executes and reports its real version.
• Every native dependency resolves.
• The service is installed and correctly disabled.
• The runner refuses to start while unregistered.
• No credential artefact of any kind is present.

The self-test includes a negative control, so a sweep that silently matched nothing cannot pass by accident.

sudo -u ghrunner /opt/actions-runner/bin/Runner.Listener --version >/dev/null 2>&1 || true
sudo bash /opt/actions-runner/runner-selftest.sh

The first run on a freshly launched instance takes a couple of minutes. This is expected and is not a fault. An EBS volume created from a snapshot loads its blocks from Amazon S3 on first access, so the runner's .NET libraries are read from S3 the first time rather than from local storage. Subsequent runs complete in a few seconds.

The command above touches the runner binary first, so that the wait happens at an obvious point rather than in the middle of the self-test.

Run the self-test again after you register. It then correctly reports the runner as configured, and the credential sweep checks that your credentials are where they belong and nowhere else.

Registering your runner

Registration is the one step that you perform yourself, and it takes about a minute.

Run the commands in this section on your instance with your token. They are intentionally not executable checks, because a registration token is specific to your account and expires within the hour.

Step 1 - Generate a registration token

In GitHub, go to the repository, organisation or enterprise that you want the runner to serve:

• Repository runner: repository > Settings > Actions > Runners > New self hosted runner
• Organisation runner: organisation > Settings > Actions > Runners > New self hosted runner

Choose Linux and x64. GitHub shows a configuration command that contains a registration token. You need only the URL and the token from that command. The runner software is already installed on this image, so skip GitHub's download steps.

The registration token is short-lived and expires within about an hour. Generate it when you are ready to use it.

Step 2 - Register

First, read your instance's generated runner name from the instructions file:

sudo grep '^runner.name=' /root/github-actions-runner-credentials.txt

Then run the configuration command as the ghrunner service account, substituting your URL, your token and that runner name:

sudo -u ghrunner /opt/actions-runner/config.sh \
  --url https://github.com/YOUR-ORG/YOUR-REPO \
  --token YOUR-REGISTRATION-TOKEN \
  --name YOUR-RUNNER-NAME \
  --work /opt/actions-runner/_work \
  --labels self-hosted,linux,x64,docker \
  --unattended

For an organisation-wide runner, use the organisation URL instead:

--url https://github.com/YOUR-ORG

config.sh exchanges your short-lived registration token for long-lived runner credentials and writes them into /opt/actions-runner. Those files are the runner's identity. Treat them as secrets, and never bake them into an image of your own.

Step 3 - Start the runner

Enable and start the service:

sudo systemctl enable --now github-actions-runner.service
sudo systemctl status github-actions-runner.service

The unit's ConditionPathExists gate is satisfied as soon as registration has written the state file, so the service now starts normally. Within a few seconds, your runner appears as Idle under Settings > Actions > Runners in GitHub and starts accepting jobs.

Running your first workflow

Add a workflow to your repository at .github/workflows/selfhosted.yml:

name: Self hosted smoke test on: [push, workflow_dispatch] jobs: build: runs-on: self-hosted steps: - uses: actions/checkout@v4 - name: Show the runner environment run: | echo "Running on $(hostname)" git --version docker --version python3 --version

Push the file, or trigger it from the Actions tab. Your runner picks up the job instead of a GitHub-hosted runner.

To target a specific runner rather than any self-hosted one, use the labels that you set at registration:

runs-on: [self-hosted, linux, x64, docker]

Runner groups, labels and fleets

Labels are how workflows select a runner. Set them at registration with --labels, or edit them later in the GitHub UI under the runner's settings. Give runners labels that describe real capabilities, for example docker, gpu or build-large, so that runs-on expresses a requirement rather than a hostname.

Runner groups let organisations control which repositories may use which runners. Create groups under Settings > Actions > Runner groups, then pass --runnergroup YOUR-GROUP at registration.

To build a fleet, launch several instances from this image. Each instance generates its own unique runner name at first boot, so they can all register into the same organisation without colliding. GitHub distributes queued jobs across whichever runners are idle.

Security model

A self-hosted runner executes whatever code your workflows contain. Treat it accordingly.

• The runner does not run as root. It runs as ghrunner, a dedicated system account with no password, no sudo rights and no sudoers entry. The agent itself refuses to run as root.
• No inbound ports. The runner connects outbound to GitHub, so the security group needs only your own SSH access. Do not open other ports for the runner, because it does not need them.
• Do not use a self-hosted runner on a public repository. This is GitHub's own guidance, and it matters. Anyone who can open a pull request against a public repository can propose workflow changes. On a self-hosted runner, that means proposing code that runs on your instance and inside your network. Keep self-hosted runners to private repositories, or gate workflow runs on approval.
• Jobs share the instance. By default, consecutive jobs run on the same machine with the same working directory tree. If your workflows handle secrets or untrusted code, isolate them. Run job steps inside containers, or treat runners as disposable and replace the instance between sensitive jobs.
• The ghrunner account is in the docker group. This membership is required for container jobs, and it is effectively root-equivalent on the instance. It is the standard trade-off for a runner that supports Docker, and it is another reason to keep the instance's network exposure minimal.
• Your registration credentials live only on your instance. config.sh creates them at registration, and they are not present in the image. If you create your own AMI from a registered runner, remove the registration first. Otherwise, you clone your CI identity onto every instance launched from the AMI.

Upgrading the runner

GitHub releases runner updates regularly, and the service refuses a runner that is too far behind. When the runner is registered and running as a service, it updates itself in place by default, so ordinary version drift is handled for you.

To check the version that is currently installed, run:

sudo -u ghrunner /opt/actions-runner/bin/Runner.Listener --version

To pin or control updates, pass --disableupdate at registration and manage upgrades yourself.

Removing a runner

To retire a runner cleanly, remove its registration from GitHub before you terminate the instance, so that it does not linger as an offline runner in your settings. Generate a removal token the same way you generated the registration token, then run:

sudo systemctl disable --now github-actions-runner.service
sudo -u ghrunner /opt/actions-runner/config.sh remove --token YOUR-REMOVAL-TOKEN

You can also remove an offline runner directly in the GitHub UI under Settings > Actions > Runners.

Backup and maintenance

There is very little state to back up. The runner keeps no database. Its state is the registration files in /opt/actions-runner and the transient _work directory. You can safely lose the _work directory, because every job checks out again what it needs.

Pay attention to the following:

• Patch the instance. The image ships fully patched at build time. Apply operating system updates on your own schedule after that.
• Watch disk usage. The _work directory accumulates checkouts and build artefacts, and Docker accumulates images and layers. If builds start failing for lack of space, prune Docker and clear old job directories.
• Monitor runner health from Settings > Actions > Runners in GitHub, which shows each runner as Idle, Active or Offline.

To see how much space the runner working area uses, run:

sudo du -sh /opt/actions-runner/_work 2>/dev/null || echo "work directory is empty"

Support

SecureAnyCloud provides 24/7 technical support for this image by email at sales@secureanycloud.com and through live chat.

We can help with deployment and first boot, registering the runner to a repository, organisation or enterprise, runner groups and labels, scaling to a fleet, configuring the systemd service, container and service container jobs with Docker, workflow and caching design, hardening the execution environment for untrusted code, network and security group rules, monitoring runner health, and runner version upgrades.

Trademarks

GitHub and GitHub Actions are trademarks of GitHub, Inc. SecureAnyCloud is not affiliated with, endorsed by, or sponsored by GitHub, Inc. or Microsoft. The runner agent distributed in this image is the unmodified official release, published by GitHub under the MIT Licence. A copy of that licence ships at /opt/actions-runner/LICENSE. All other product and company names are trademarks or registered trademarks of their respective holders.

Deploy on AWS

Launch GitHub Actions Runner on AWS with 24/7 support from SecureAnyCloud.

View on Marketplace

Need Help?

Our support team is available 24/7.

sales@secureanycloud.com