GitLab Runner Setup on Ubuntu

GitLab Runner is the agent that obtains CI/CD jobs and executes them through an executor. A reliable setup requires more than installation: the host, registration workflow, executor, tags, permissions, network access, and maintenance policy define the runner’s security boundary.

Choose the runner scope and executor#

A shell executor runs commands directly on the Ubuntu host and should be reserved for highly trusted workloads. Container-based execution improves repeatability but still requires image governance, limited privileges, and careful volume and socket access.

Prepare Ubuntu safely#

• Use a supported Ubuntu release and install current security updates.
• Create dedicated storage and monitor free disk space.
• Limit inbound access and outbound destinations.
• Synchronize time and configure centralized logs.
• Avoid co-locating unrelated sensitive services on the runner.
• Plan how runner packages and executors will be upgraded.

Install and register#

Use GitLab’s current package instructions for the Ubuntu version, then register through the workflow provided by the target GitLab instance. Treat registration material as sensitive, assign descriptive tags, disable untagged-job handling unless intended, and lock the runner to the correct scope when appropriate.

Validate with a harmless job#

1. Confirm the runner service is active.
2. Verify the runner appears online in GitLab.
3. Run a job that prints tool versions without secrets.
4. Check that tags route the job to the intended runner.
5. Confirm artifacts and logs are returned correctly.
6. Test job timeout, cancellation, and cleanup behavior.

Hardening priorities#

• Do not expose the container-engine socket to untrusted jobs.
• Avoid privileged containers unless the threat model explicitly permits them.
• Separate protected deployment runners from merge-request runners.
• Use ephemeral cloud credentials and narrow job-token permissions.
• Patch the host, runner, executor, and base images.
• Remove stale runners and rotate credentials after compromise.

Troubleshooting#

GitLab Runner installation documentation