# Connect a GitLab project

> Add RealHW as a project runner for GitLab.

Source: https://docs.realhw.dev/get-started/connect-gitlab-project/
Documentation index: https://docs.realhw.dev/llms.txt

Connect each GitLab project to RealHW with one project runner. After the runner is connected, jobs choose hardware with `tags` in `.gitlab-ci.yml`.

## Prerequisites

- A GitLab project where you can manage project runners
- A RealHW account with available units or an assigned billing group
- A GitLab personal access token if you want RealHW to create the runner for you

## Managed setup

Use managed setup when your GitLab policy allows RealHW to create the runner.

1. Open the RealHW dashboard.
2. Select **Create project runner**.
3. Enter the GitLab instance URL, usually `https://gitlab.com`.
4. Enter the GitLab project ID or project path.
5. Choose the initial runner tags for this project.
6. Provide a GitLab personal access token with runner creation permissions.
7. Save the runner.

RealHW stores the GitLab runner token server-side. You should not need to copy `glrt-*` runner tokens in the normal path.

## Manual import

Use manual import when your organization does not allow third-party runner creation with a personal access token.

1. Create a project runner in GitLab.
2. Copy the runner authentication token.
3. Open the RealHW dashboard.
4. Select **Import runner**.
5. Paste the token and choose the tags RealHW should expose.

Manual import can be more limited. RealHW may not be able to update GitLab-side tags, pause the runner, delete the runner, or rotate the runner token.

## Verify

In GitLab, confirm the project has an active runner with the tags you selected. In RealHW, confirm the runner status is active.

Next, [run your first job](https://docs.realhw.dev/get-started/run-your-first-job/).