Halloween DealsAmazon USHalloween week deals: useful picks before month-endAmazon US: current deals, useful picks and tech finds.Check DealsPC HealthRecommendedCrashes, freezes, slowdowns? Check your PC nowSpot repairable issues before they interrupt work.Check PCHalloween DealsAmazon USOctober picks are moving - compare before checkoutAmazon US: current deals, useful picks and tech finds.See Picks×
FREEDOM251

Freedom251 › Blog › Continuous integration

How to Set Up GitLab CI and a Runner on Your Own VPS

By Freedom251 Team · · 12 min read

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

To run GitLab CI jobs on your own VPS, create a project-root .gitlab-ci.yml, provision a supported Linux server, install GitLab Runner, create a runner in Settings > CI/CD > Runners, register it with the generated authentication token, choose an executor, start the service, and run a pipeline. The YAML file defines what the pipeline does; the runner is the agent that executes those jobs. Use the shell executor for simple, trusted workloads that can run directly on the host, or the Docker executor when container isolation and repeatable build images are more important.

What you are building

GitLab CI has two parts that are easy to confuse:

  • Pipeline configuration: A file named .gitlab-ci.yml in the repository root defines stages, jobs, scripts, variables, dependencies, and conditions. The filename is case-sensitive.
  • Runner: GitLab Runner is the service installed on your VPS. Registration links that service to GitLab so it can request and execute jobs from the project pipeline.

When you push a commit, GitLab reads the YAML file and creates jobs. It then looks for an available runner whose scope and tags match each job. The runner checks out the code, prepares the selected executor, runs the commands, and sends the log and result back to GitLab.

As an Amazon Associate I earn from qualifying purchases.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

Keeping the runner on your own VPS gives you control over the operating system, network location, installed tools, storage, and maintenance schedule. It also makes the VPS part of your security boundary: untrusted CI code can affect the runner host if you choose a shell executor or grant containers excessive privileges.

Before you begin

Access and account requirements

  • A GitLab project where you can add or edit repository files and manage runners.
  • Administrator access to a Linux VPS, normally through SSH, with permission to install packages and run services.
  • Outbound network access from the VPS to your GitLab instance over HTTPS. The runner must be able to resolve the GitLab hostname and maintain connections while jobs are running.
  • A decision about whether this runner should serve one project, several projects in a group, or an entire GitLab instance.

Choose a supported VPS platform

GitLab documents Linux support and multiple CPU architectures. Select a distribution and architecture listed as supported at the time you deploy; package names and service commands vary between distributions. There is no universal CPU or RAM requirement for a runner. Size the VPS from the jobs it will execute, including compiler workload, dependency downloads, test parallelism, Docker image size, artifact storage, and the number of concurrent jobs.

#1 Best Overall
Sale
TOZO A1 Wireless Earbuds Bluetooth 5.3 Light Weight in Ear Headphones | IPX5 Waterproof,2 Mics for AI Calls,Immersive Premium Sound Bass Headset with Charging Case,32 EQ via App Black
  • [Ultra-Lightweight Ear Buds Designed for Small Ears] Each earbud weighs only 3.7g and features a compact, ergonomic in-ear design made especially for small ears. Secure, low-profile, and comfortable for workouts, all-day wear or overnight sleeping.The ultra-slim profile sits flush in your ear with no hard edges poking or rubbing, so you can even sleep on your side without discomfort.
  • [Immersive Stereo Sound with TOZO OrigX Technology] TOZO OrigX tuning delivers clear vocals, balanced mids, and natural stereo sound for music, podcasts, and videos.
  • [Long Battery Life for Daily Use] Get up to 7 hours of playtime on a single charge, with up to 32 hours total using the charging case—ideal for workdays, commuting, and extended listening sessions.
  • [Bluetooth 5.3 & Stable Connection] Bluetooth 5.3 provides fast pairing, stable wireless performance, and reduced dropouts as you move around home or office.
  • [Deep Bass with Clear Vocals] High-performance drivers produce punchy bass while keeping vocals clean and detailed for everyday listening.

Leave capacity for the operating system and the runner itself. A server that is adequate for a single lightweight lint job may become unusable when several builds compile at once. Start with a measured workload, watch CPU, memory, disk, and network usage, and resize or add runners when sustained saturation causes queueing or failures.

Step 1: Add a project pipeline file

Create .gitlab-ci.yml at the top level of the repository. GitLab will not recognize a similarly named file in a subdirectory or a file with different capitalization.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

This minimal example creates sequential build and test stages:

stages:
  - build
  - test

build_job:
  stage: build
  script:
    - echo Building

test_job:
  stage: test
  script:
    - echo Testing

Commit and push the file. GitLab parses it when a pipeline is created. In a real project, replace the demonstration commands with dependency installation, compilation, tests, packaging, or deployment commands appropriate to your application. Add variables for non-secret configuration and use GitLab’s protected or masked CI/CD variables for credentials rather than placing secrets in this file.

Stages run in the order listed. Jobs in the same stage can run in parallel when enough matching runners are available. A job can also specify tags, conditions, dependencies, caches, artifacts, and a particular container image; those choices belong in the YAML file, not in the runner registration itself.

Step 2: Provision and harden the Linux VPS

  1. Choose a supported Linux distribution and CPU architecture from GitLab’s current requirements documentation.
  2. Create a non-root administrative account and use SSH keys where your hosting platform supports them. Keep root login and password authentication restricted according to your organization’s policy.
  3. Apply operating-system updates, configure the firewall, and permit only the administration and application traffic the server needs. The runner normally needs outbound HTTPS; do not expose its service port to the public internet.
  4. Set the hostname and time synchronization. Consistent time makes service logs and token troubleshooting easier.
  5. Decide where source checkouts, caches, artifacts, and Docker layers will live. Monitor disk usage because a full filesystem can make otherwise healthy jobs fail.

For production workloads, isolate the runner from unrelated services when practical. GitLab’s runner chart documentation recommends installing a production runner on a separate machine for security and performance reasons. A dedicated VPS also makes resource accounting and incident response clearer.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.
Rank #2
Sale
Smart Watch for Men Women Compatible with iPhone Samsung Android Phone 1.69 inch Full Touch Screen IP68 Waterproof Bluetooh Fitness Tracker Heart Rate/Sleep Monitor (Black)
  • 【IP68 Waterproof Multifunctinal Smart Watch】Torjalph fitness activity tracker smart watch is IP68 waterproof technology ,you can wear it when swimming,handwashing,it's rain-proof which means that you perform multiple exercise modes outside without worrying about sweat or rain corroding your fitness smart watch,and this watch equipped with a 230 mAh large capacity battery magnetic charging ,and this sports activity tracker watch can be used 5-7 days If fully charged.
  • 【Larger 1.83'' Full Screen Watch & Multi-dial Selection】1.83 inch full HD color touch screen smart watch for men / women provides excellent 240*284 resolution image quality ,This Bluetooth smart watch offers a better touch experience and remarkable immersion and ,more than 200 watch faces for you to choose from App"Da Fit ", you can change the dial style according to your mood to wear keeping the world on your wrist
  • 【Accurate Activity Tracker Smart Watch 】sports watch activity tracker uses sweat and dust resistant breathable silicone strap, our Fitness Tracker Smart Watch for Android iOS Phones supports 12 sports modes,walking,running,bicycle,swimming,badminton,basketball,football,rope skipping. This bluetooth calls smart watch for men women is lightweight and stylish, bringing more convenient and relaxing sports experience while also providing more protection.
  • 【Your 24 Hour Personal Daily Health Monitor】Fitness watch for women men full touch screen IP67 waterproof bluetooth smartwatch for Android iOS Phones with heart rate blood pressure monitor multifunction Andriod smart watch with steps counter sleep monitor sports fitness watch, monitoring blood oxygen saturation allows you to understand your physical condition in real time to track fitness progress ,to know your health status in time.
  • 【More Functions Bluetooth Call Smart Watch】This fitness activity smart watch full screen for iPhone and Android phones includes a bunch of new features including:The bluetooth smart watch can hang up the phone, receive and display WhatsAPP /Text /Facebook /Twitter /Messenger reminder.Support sedentary reminder, alarm clock, stopwatch, timer,weather information,music control, remote camera control compatible with Android 5.0 and above or iOS 9.0 and above smartphones.

Step 3: Install GitLab Runner

Install the runner package from GitLab’s official Linux repository or use another installation method documented by GitLab for your distribution. Treat installation scripts and package sources as privileged code: inspect scripts before execution, verify that the repository is trusted, and keep the package updated.

After configuring GitLab’s repository, Debian- or Ubuntu-based systems commonly install the package with:

sudo apt-get update
sudo apt-get install gitlab-runner

On an RPM-based system, the equivalent package command may be:

sudo dnf install gitlab-runner

Use the command syntax documented for your exact distribution rather than assuming these examples apply unchanged. A binary installation is another documented option when a package repository is not suitable. Confirm that the gitlab-runner executable is available before registering it.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

For a Docker executor, install and configure Docker separately using the Docker documentation for your distribution. The runner service account must be able to invoke Docker, but adding that account to a privileged Docker group effectively grants host-level control; make that trade-off deliberately and do not use the arrangement for untrusted code without an appropriate isolation plan.

Step 4: Create the runner in GitLab

  1. Open the project in GitLab.
  2. Go to Settings > CI/CD and expand Runners.
  3. Choose to create a project runner, or select a group or instance runner when the runner must be shared at that scope.
  4. Choose whether the runner may accept untagged jobs. Disable that option when you want every job to declare an explicit routing tag.
  5. Give the runner a descriptive name and add tags if it has a specialized purpose, such as a particular operating system, toolchain, architecture, or deployment network.
  6. Copy the authentication token shown during runner creation. Store it as a secret; do not commit it to the repository, paste it into tickets, or place it in shell history that other users can read.

Current GitLab documentation uses the runner creation and authentication-token workflow. Older registration-token workflows are deprecated, so do not build a new setup around an obsolete registration token.

Rank #3
New Bee Guitar Cable 10ft Electric Instrument Bass AMP Cord
  • [Low Noise High Fidelity] New bee guitar cord with 22AWG oxygen-free-copper center conductors provides enhanced signal transfer, the PVC insulation material and the high-density stranded copper double shield provide noise rejection for quiet operation
  • [Ideal for Choice] New bee 1/4 straight and right angle metal connectors, ensures a secure connection in any instrument, pedal, or amp jack. L shape great fro on stage guitar stands
  • [Wide Compatible] Suitable for mixer, power amplifier, microphone, effector, decoder, equalizer, electoronic organ, electric guitar, electric bass and other electronic equipments. Widely used in the installation of smart home, karaoke speaker, professional stage audio, etc
  • [Easy Disassemble] Making incidental repairs quick and easy! Very nice, flexible cable
  • [Dont Hesite to Order] 24 hours customer services and professional technology team are standing by

Step 5: Register the runner on the VPS

Run the registration command as the account that owns the runner service, commonly with elevated privileges:

sudo gitlab-runner register

The interactive prompts ask for four essential values:

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.
  1. GitLab instance URL: Enter the URL of the GitLab instance that hosts the project, including the correct scheme and hostname.
  2. Authentication token: Paste the token generated in the project, group, or instance runner screen.
  3. Runner name: Use a name that identifies the VPS and its role, not a personal nickname.
  4. Executor: Enter shell for direct host execution or docker for containerized jobs.

Registration writes the runner definition and token to its configuration, normally config.toml. If you register several runners on one host, keep their names, tags, and executor choices distinct so an operator can identify the correct entry later.

Shell executor

The shell executor runs each job directly on the VPS operating system. It has the lowest setup overhead and can use tools already installed on the host, but scripts share the host filesystem, users, processes, credentials, and network. A job that deletes files or installs software can affect subsequent jobs and the server itself. Use it only for projects and contributors you trust, and run it on a host that does not contain unrelated production secrets.

Docker executor

The Docker executor starts jobs in containers. A selected image supplies a more repeatable userspace and creates a boundary between the job process and the base host, while still requiring careful configuration. You must maintain Docker, pull or build suitable images, provide any required caches or services, and account for image download and container startup time. Docker is not a complete security boundary when the job can access the Docker socket or privileged containers; review mounts, capabilities, networks, and secrets before allowing untrusted code.

Shell versus Docker: choose the executor deliberately

Consideration Shell executor Docker executor
Isolation Jobs run directly on the VPS and share its operating system. Jobs run in containers, providing a stronger runtime boundary when configured correctly.
Reproducibility Depends on the tools and versions installed on the host. Images can pin a userspace and toolchain for repeatable jobs.
Startup overhead Very small; commands start on the host. Requires container creation and, when needed, image pulls.
Host access Direct access to host files, processes, network, and installed credentials. Limited by container mounts and permissions, but Docker-socket or privileged access can remove much of that protection.
Maintenance Maintain every compiler, SDK, runtime, and version on the VPS. Maintain Docker and the images, registries, caches, and cleanup policy.
Best fit Trusted internal projects, simple scripts, or jobs that require host-level tools. Projects needing consistent build environments or separation between job filesystems.

Changing the executor is not a YAML-only change. It changes where commands run and what software and permissions they can see. Register a separate runner when you need both behaviors instead of weakening the security model of an existing runner.

Rank #4
BSIMB 15.6" Digital Family Calendar & Chore Chart, No Subscription Fees
  • Digital Family Calendar: BSIMB digital calendar wall touch screen puts an end to your chaotic life. Designed for busy families, the digital calendar keeps you organised and in step with your family. Assign different colours and tasks to each family member to make family scheduling easier and more intuitive.
  • Easy Setup and Auto-Sync: Plug in, connect to WLAN and auto-syn your electric calendar in minutes. Digital wall calendar compatible with Google calendar, iCloud calendar, Outlook calendar, Cozi calendar and Yahoo calendar. Add events directly on the device or through the ecalendar app. Electronic calendar stays current whether you're at work or traveling—no manual updates needed.
  • All-In-One Home Assistant: Smart calendar builds habits and encourage independence with personalised chores. Display daily meal plan to reduce the daily ‘What's for dinner?’ stress. To-do lists keep track of everything you want. Turning chores into valuable achievements with stars and rewards, making life easier and more enjoyable.
  • Manage Anytime Anywhere: BSIMB electronic calendar for family stay connected with the powerful ecalendar app. Access and manage your digital wall calendar anytime, anywhere with free features like stars & rewards, photo screensaver, chore charts, meals plans, to-do lists etc. Electronic planner paid features like Magic Import tailor advanced tools for users with special needs.
  • Stay in Touch with Loved Ones: Share photos or videos from your phone to electronic wall calendar with app, instantly update your life moment, and keep in touch with your family, especially those who are far away; you can also surprise your smart calendar digital wall by sending him a wish card; it's also great for keeping tech-illiterate elders in touch with the youngsters.

Step 6: Start the service and verify registration

Enable and start the service using the service manager supplied by your distribution. On systems using systemd, a typical sequence is:

sudo systemctl enable --now gitlab-runner
sudo systemctl status gitlab-runner

If your installation uses a different service manager, use the corresponding GitLab Runner command or distribution documentation. The status should show an active process without repeated authentication or configuration errors. The runner should appear as online in the project’s Settings > CI/CD > Runners page.

You can also ask the installed client to verify its registered runners:

What’s actually slowing this PC down?

Pick the symptom - the matching free tool is one click away.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.
sudo gitlab-runner verify

Registration alone does not prove that a job can execute. Trigger a pipeline by pushing a commit or using GitLab’s manual pipeline action, then open the job log. A healthy log shows checkout, executor preparation, script execution, and an exit status of zero for successful commands.

Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.Support on Ko-Fi

Step 7: Route jobs with runner scope and tags

Runner scope

Scope Use it when Primary trade-off
Project runner The VPS should serve one project or one tightly controlled repository. Narrow blast radius and simple ownership, but no automatic sharing with other projects.
Group runner Several projects in the same group need the same capabilities and trust boundary. Less duplication, but every permitted project can consume the runner and influence its workload.
Instance runner An administrator intentionally provides a common pool for many projects. Centralized administration and broad capacity, with the largest sharing and trust boundary.

Choose the narrowest scope that meets your sharing requirement. Separate production deployment runners from general build runners so an ordinary test job cannot reach deployment credentials or networks.

Tags are the routing filter

Tags are the only way to filter the list of available runners for a job. Add tags to the runner during creation or in its configuration, then use matching tags in the job definition:

build_job:
  stage: build
  tags:
    - linux-docker
  script:
    - ./build.sh

A job that declares a tag can run only on a runner carrying that tag. If a job has no tags, it can use a runner configured to accept untagged jobs. When a job remains pending, compare the job’s tags with the runner’s tags character for character and check that the runner is enabled for the project.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

Step 8: Protect tokens, files, and workloads

  • Protect the runner authentication token and the config.toml file. Restrict read access to the service account and administrators, and never store the token in Git.
  • Use protected and masked CI/CD variables for passwords, API keys, signing keys, and deployment credentials. Limit sensitive variables to protected branches or tags.
  • Do not expose a privileged shell runner to untrusted merge requests. Shell jobs can read or alter anything the runner account can access.
  • For Docker jobs, review privileged mode, host-path mounts, Docker-socket access, Linux capabilities, network access, and image provenance.
  • Keep the runner host separate from unrelated production services when possible. A compromised build should not automatically become a production compromise.
  • Apply operating-system, runner, Docker, and build-image updates on a maintenance schedule. Test updates on a non-production runner first when the workload is critical.
  • Set disk and log monitoring. Remove stale work directories, unused images, and obsolete caches according to a retention policy.

Why a runner is offline or not receiving jobs

The runner is offline in GitLab

  1. Check the service: sudo systemctl status gitlab-runner. Restart it only after reading the recent error output.
  2. Run sudo gitlab-runner verify and inspect the runner configuration for a mistyped GitLab URL or damaged token.
  3. Test DNS resolution and outbound HTTPS from the VPS. A firewall, proxy, or incorrect certificate chain can prevent the runner from contacting GitLab.
  4. Confirm that the runner has not been paused, disabled, or removed at its project, group, or instance scope.
  5. Inspect the service journal and config.toml permissions. The service account must be able to read its configuration.

The job is pending and says no runner is available

  • Compare every job tag with the runner’s tags. A spelling or capitalization difference prevents matching.
  • If the job has no tags, verify that the runner accepts untagged jobs.
  • Confirm that the runner belongs to the project or to a group/instance scope that the project can use.
  • Check whether the runner is already busy and whether its configured concurrency is sufficient for the workload.
  • Verify that the selected executor can satisfy the job. For example, a Docker job may wait or fail if Docker is not installed or the service account lacks permission.

The job starts but fails on the shell executor

Read the first failing command in the job log, then reproduce it as the runner service account on the VPS. Missing packages, a different PATH, file permissions, host-level environment assumptions, and leftover files from earlier jobs are common causes. Install required tools explicitly or move the job to a Docker image that defines them.

The Docker job cannot start

Check that the Docker daemon is running, the runner account can invoke it, the requested image exists and can be pulled, and the VPS has enough disk space. Review registry credentials and proxy settings when image pulls fail. If a job depends on services or mounted directories, verify those declarations in the pipeline configuration and avoid granting broader host access than necessary.

Operate and maintain the runner

Useful lifecycle commands

sudo gitlab-runner list
sudo gitlab-runner verify
sudo systemctl restart gitlab-runner
sudo systemctl stop gitlab-runner
sudo systemctl start gitlab-runner

Command availability can differ between package and binary installations, so use the service manager and runner version installed on your VPS. Back up config.toml securely before changing registrations, and do not place that backup in the repository.

Updating or replacing a VPS

Record the runner scope, tags, executor, image requirements, variables, and any host tools before rebuilding a server. Install the same supported runner version or a tested upgrade, register the replacement with a new authentication token, run a test pipeline, and only then remove the old runner. This avoids a queue with no eligible executor.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

Scaling beyond one runner

Add runners when jobs have incompatible operating systems, architectures, trust levels, or deployment networks. Use tags to make those boundaries explicit. More runners improve parallel capacity only when the VPS network, storage, registry, and GitLab concurrency limits can support the additional jobs; otherwise, extra agents simply increase contention.

Validation checklist

  • .gitlab-ci.yml is at the repository root with exact capitalization.
  • The file defines at least one stage and one job with a valid script.
  • The VPS runs a GitLab-supported Linux distribution and architecture and has capacity for the expected concurrency.
  • GitLab Runner was installed from a trusted, documented source.
  • A project, group, or instance runner was created with the current authentication-token workflow.
  • The runner was registered with the correct GitLab URL, token, name, and executor.
  • The service is running and the runner appears online.
  • Job tags and the runner’s tags match, or untagged jobs are intentionally allowed.
  • A test pipeline completes checkout, preparation, scripts, and artifact handling successfully.
  • Tokens, configuration files, CI/CD variables, host access, and Docker privileges are protected.

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.

Continuous integrationDevOpsDockerGitLab CIGitLab RunnerLinuxVPS

Leave a Reply

Your email address will not be published. Required fields are marked *

Free tools Windows power users keep installed

One-click scans. No signup required.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

Recommended PC Tool
Recommended PC Tool
Crashes, No Sound, or Screen Glitches?Free driver scan
PC Slower Than It Used to Be?Free scan - under a minute

Two free Windows tools

One Free Minute Could Fix That PC

Before you go - each of these free tools takes about a minute and tackles what quietly slows a Windows PC down.

Special offer. View Outbyte info, uninstall instructions, EULA, and Privacy Policy.