How to Reset and Configure a GitLab Runner

Hello, I'm Ganesh. I'm working on FreeDevTools online, currently building a single platform for all development tools, cheat codes, and TL; DRs — a free, open-source hub where developers can quickly find and use tools without the hassle of searching the internet.

You push code, check the pipeline, and stare at a "Pending" status that never changes. Your GitLab Runner is technically online, but it refuses to pick up jobs, or perhaps you have old configuration ghosts haunting your server.

Sometimes, troubleshooting the existing configuration takes longer than just wiping the slate clean.

In this guide, I will walk you through how to completely remove an old, broken runner and set up a fresh, project-specific Runner using the shell executor. This approach is particularly useful if you need your runner to execute commands directly on the host machine (like Nomad or Docker commands) without complex Docker-in-Docker setups.

Stop and Create New Runner

Before we touch GitLab, we need to ensure the server hosting the runner (let's call it server-1) is clean. If you have old registrations lingering, the new one might conflict.

SSH into your server and run the following commands to stop the service and unregister any existing runners.

# 1. Stop the service
sudo gitlab-runner stop

# 2. Unregister (delete) all existing runners from this machine
sudo gitlab-runner unregister --all-runners

# 3. Start the service again (it will be empty now)
sudo gitlab-runner start

# 4. Verify it is clean (Should show nothing or 0 runners)
sudo gitlab-runner verify

You go to your project settings and see the old runner listed, but there is no trash icon to delete it.

This usually happens because you are looking at an Instance Runner (a global runner) from inside a Project View. Even if you are an Admin, GitLab often restricts deleting global runners from the project level.

To actually remove the old "Zombie" runner, you need to head to the Admin Area:

1. Click the Admin Area icon in the top navigation bar (usually looks like a wrench or dashboard).

2. On the left sidebar, navigate to CI/CD > Runners.

3. Find the old runner (e.g., server-1).

4. Here, you will finally see the Delete button. Remove it to clear the confusion.

5. Create a New Instance Runner.

6. Assign tags to the runner.

7. Select the Platform.

8. Follow these steps to start the runner.

Registration and the Shell Executor

Back on your server terminal, initiate the registration:

sudo gitlab-runner register

You will be prompted for a few inputs. Here is how to answer them:

• GitLab instance URL: Enter your domain (e.g., https://yourdomain.com).

• Registration token: Paste the token you just copied.

• Description: server-1

• Tags: server-1

• Executor: Type shell

Why the Shell Executor?

I chose shell because it allows the Runner to execute commands directly on your server's terminal. This is perfect if your pipeline needs to access tools already installed on the machine, such as Nomad, Docker, or specific Makefiles, without the overhead of spinning up containers for every job.

Creating a Project Specific Runner

Now that the old runner is gone, let's create a new one properly. It is generally better practice to create a Project Runner rather than an Instance Runner, as it keeps your CI environment isolated to the specific repository.

1. Go to your specific Project page (e.g., org/project1).

2. Navigate to Settings > CI/CD.

3. Expand the Runners section.

4. Click New Project Runner.

5. Tags: Enter a tag like server-1 (Make sure to press Enter so it creates the blue chip).

6. Description: Give it a clear name.

7. Click Create runner and copy the token. You won't see this token again.

Understanding the "Leftovers"

It is important to understand the trade-off when using the shell executor.

When you use a Docker executor, the runner spins up a fresh container for every job and destroys it afterwards. It is perfectly clean.

When you use a Shell executor, the runner is operating on your actual server's filesystem.

1. Old Build Data: Even after unregistering a runner, the old build artifacts often remain in /home/gitlab-runner/builds/. If you want a 100% clean slate, you may need to manually run:

    sudo rm -rf /home/gitlab-runner/builds/*
    sudo rm -rf /home/gitlab-runner/cache/*
   

2. Disk Space: Since the environment isn't destroyed after every job, temporary files or installed packages will accumulate. If your pipeline installs software (like apt install jq) or downloads large assets, they stay there forever unless your script explicitly deletes them.

Final Verification

Once registered, run this command on your server one last time:

sudo gitlab-runner verify

If it returns "is valid," you are good to go. Head back to your GitLab Jobs page, and you should see your pending pipelines kicking into gear.

I’ve been building for FreeDevTools.

A collection of UI/UX-focused tools crafted to simplify workflows, save time, and reduce friction when searching for tools and materials.

Any feedback or contributions are welcome!

It’s online, open-source, and ready for anyone to use.

👉 Check it out: FreeDevTools
⭐ Star it on GitHub: freedevtools