iTechGuides is reader-supported. When you buy through links on our site, we may earn an affiliate commission. As an Amazon Associate I earn from qualifying purchases. Learn more
Attaching a runner means registering a worker program with a CI/CD platform so the platform can send it jobs. In GitLab, that registration links a runner to your GitLab instance using a runner authentication token, and the runner then writes its connection details to a local config.toml file. Until that link exists, the runner sits idle no matter how well the machine is set up. This guide explains what a runner does, what registration changes, how hosted and self-managed options differ, and where scope and token handling cause problems. GitLab is used as the detailed example; GitHub Actions uses a similar idea with a different setup, and it is covered separately below.
What a runner does in a CI/CD pipeline
A runner is the worker that carries out CI/CD jobs. When a pipeline is triggered, the platform makes the jobs available, and a runner that is eligible for a job picks it up, prepares an execution environment, runs the configured commands and reports the results back. Build, test and deploy steps all run on runners rather than on the platform’s own servers, which is why a pipeline can be stuck or failing for reasons that have nothing to do with your code.
| # | Preview | Product | Price | |
|---|---|---|---|---|
| 1 |
|
CI/CD with GitHub Actions: Automate Your Build, Test, and Deployment Pipeline | $2.99 | Buy on Amazon |
GitLab describes runners as agents that run the GitLab Runner application. Its documented flow is: register the runner, make jobs available when a pipeline is triggered, match runners to jobs, execute the job, and report results. The matching step is where most “my job never starts” problems originate. See the GitLab runners overview for the full model.
What “attaching” means in GitLab
“Attaching” is not a universal DevOps command. In GitLab it corresponds to registration: telling a GitLab Runner installation which GitLab instance to contact and which credential to use. Registration does three things:
#1 Best Overall
- It records the GitLab instance URL the runner will talk to.
- It stores a runner authentication token that identifies that runner to GitLab.
- It writes the resulting configuration, including the token, to
config.tomlon the runner host.
Registration does not start any jobs by itself. It makes the runner eligible to receive them, and jobs still have to match the runner’s tags and other requirements, as explained in the matching section below.
Step by step: registering a GitLab runner
- Create the runner in GitLab and obtain its token. Create an instance, group or project runner in GitLab’s runner management screen. Choose the scope first, because it determines which projects can use the runner (see the scope section). The current registration page says the authentication token can be obtained this way or by locating it in an existing
config.toml. Interface labels in GitLab change over time, so follow the current screen names in the GitLab registering runners page. - Install GitLab Runner on a separate server. The registration documentation calls for a server separate from the GitLab installation. For Docker, install GitLab Runner in a Docker container on that host.
- Run
gitlab-runner register. Enter the GitLab instance URL. For a self-managed installation, use your instance’s address. For GitLab.com, the URL ishttps://gitlab.com. - Enter the authentication token. Paste the runner authentication token you obtained in step 1.
- Enter a description and tags. The description is for people who manage the runner. Tags are what jobs use to request this runner, so choose them deliberately; a mistyped tag is a common cause of jobs that wait indefinitely.
- Check the result. Confirm the new entry appears in
config.tomland that the runner shows as available in GitLab. Then trigger a pipeline that targets the runner’s tags.
The legacy registration token
Older guides describe registering with a runner registration token. The current registration page marks these tokens as deprecated and scheduled for removal in GitLab 20.0. If an older script or runbook still depends on one, move it to a runner authentication token now rather than waiting for the removal. Check the current registration page for the latest status, since removal timing is a version-dependent detail.
Hosted versus self-managed runners
The most consequential decision is who operates the machine that executes jobs. GitLab offers hosted runners that GitLab manages, and self-managed runners that run on infrastructure your organization operates.
Recommended Free Tools
| Factor | GitLab-hosted runners | Self-managed runners |
|---|---|---|
| Infrastructure you manage | None; GitLab manages the runners | The host, its operating system, updates and capacity |
| Setup needed | Available without setup, per GitLab’s runner overview | Install GitLab Runner, then register it (see steps above) |
| Execution environment | A fresh VM for each job | Depends on your configuration; reuse can be tuned for speed |
| Scaling | Scales automatically, per GitLab’s documentation | Scales with the hosts you provision |
| Customization | Not presented by GitLab as the route for custom setups | GitLab lists customization as a reason to choose self-managed runners |
| Private network access | Not presented by GitLab as the route for private-network work | GitLab lists private-network use as a reason to choose self-managed runners |
| Security controls | Managed by GitLab | Your own controls, which GitLab lists as a reason to choose this option |
| Hardware ownership | GitLab’s | Yours |
The practical rule is simple. If your jobs need nothing beyond the hosted environment, a hosted runner removes the host from your responsibilities. If jobs need to reach internal systems, need special software or controls, or you want to reuse an environment for speed, a self-managed runner is the documented route. For background, see the GitLab runners overview and the runner configuration page.
Requirements for a self-managed GitLab runner host
- A server separate from the GitLab installation, or a Docker host if you use the containerized path.
- Network access from the host to your GitLab instance so the runner can reach it.
- Someone responsible for updates, patching and capacity, because these are now your responsibility.
- A plan for the authentication token stored in
config.toml, covered in the security section.
Scope: project, group and instance runners
Scope decides which work a runner can receive. GitLab’s runner management documentation covers group runners and describes a process that provides traceability of runner ownership. Use the most restrictive scope that does the job.
| Scope | What it is for | Main risk to check |
|---|---|---|
| Project runner | One project’s jobs | Low reach; confirm the project is the only consumer |
| Group runner | Jobs across a group’s projects | Every project in the group can use it; check ownership and access |
| Instance runner | Available across the instance | GitLab documents greater security risk because it is available by default to all groups and projects in the instance |
Scope and tags work together. A runner with a broad scope can still be restricted to certain jobs with tags, but scope is the first line of control. The GitLab manage runners page covers how these scopes are managed in practice.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.Why jobs stay pending: tags and matching
A registered runner is not automatically used by every job. GitLab matches runners to jobs using tags, runner type, status, capacity and required capabilities. Troubleshoot in this order:
Do these 3 things before closing this tab:
1Clear out junk files and repair common Windows errors2Fix the driver behind crashes, sound loss and screen glitches3Repair Windows errors before they cause bigger problems- Tags. Confirm the job’s tags exactly match the runner’s tags. A runner with no matching tag will not necessarily pick the job up.
- Scope. Confirm the runner’s scope includes the project that triggered the job.
- Status. Confirm the runner process is running on the host and shows as available in GitLab.
- Capacity. A busy runner may leave jobs waiting even when everything else is correct.
Most “attached but idle” cases fall into the first two items.
Tokens and secrets
The runner authentication token identifies the runner to GitLab, and it is stored locally in config.toml. Treat that file as sensitive: anyone who can read it can act as that runner. Keep the runner’s access limited to the projects and groups that need it, restrict who can log in to the host, and avoid copying config.toml between machines without a reason. The GitLab documentation identifies where the token lives, but it does not provide a complete secret-management procedure for your environment, so set one based on your own controls. The GitLab token overview describes the token types in more detail.
GitHub Actions: a different setup under a similar name
GitHub Actions also uses the phrase “self-hosted runner,” but the procedure is not the same as GitLab’s registration. In GitHub’s model, a machine you configure must run the runner application and connect to GitHub. The reference page sets these requirements:
- The runner application must be running on the host machine to accept jobs.
- The machine needs outbound HTTPS access on port 443.
- The documented minimum is 70 kilobits per second of upload and download speed. This is a stated minimum in GitHub’s current self-hosted runner reference, not a performance target.
Do not reuse GitLab commands or token steps for GitHub. Follow the GitHub self-hosted runners reference for that platform’s setup.
The Tool Desk
Outbyte Driver Updater FREEFix the driver behind crashes, sound loss and screen glitchesFind Drivers →Outbyte PC Repair FREEClear out junk files and repair common Windows errorsFree Scan →Choosing the right path
- Use a hosted runner when your jobs need only the hosted environment and you do not want to operate a machine.
- Use a self-managed runner when jobs must reach private networks, need custom software or controls, or benefit from reusing an environment.
- Use a project runner when one project is the only consumer. Move to group or instance scope only when the wider reach is intentional.
- Check tags first when a registered runner is not picking up jobs.
When you are unsure which platform a runner belongs to, check the CI/CD system’s own documentation before running any command. The word “runner” appears on both platforms, but the attachment steps differ.
Quick Recap
“
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
