Skip to content

GitLab Runners

GitLab Runners are agents that run your CI/CD jobs and execute the scripts defined in your .gitlab-ci.yml file.

How Runners Execute Jobs

When a pipeline is triggered in GitLab and a job is ready to run, a configured runner performs the following steps:

  • Polling: The runner continuously polls the GitLab instance via its API, checking for available jobs that match its configuration (including any specified tags).
  • Job Pickup: If a job is found that the runner is eligible to execute, the runner picks it up. GitLab then marks the job as "running".
  • Code Checkout: The runner clones the project's repository to a temporary directory on the runner machine. It checks out the specific commit associated with the pipeline run.
  • Environment Setup: Based on the job's configuration in .gitlab-ci.yml (e.g., the specified image for Docker executor), the runner sets up the execution environment. For a Docker executor, this involves pulling the specified Docker image and starting a container where the job's scripts will run. This ensures a clean and consistent environment for each job.
  • Script Execution: The runner executes the commands listed under the script keyword in the .gitlab-ci.yml for that specific job. These scripts are run sequentially within the job's environment. The runner captures the standard output and standard error from these commands.
  • Reporting Status and Logs: As the scripts run, the runner streams the captured output (the job logs) back to the GitLab instance in real-time. It also reports the status of the job (ex. running, success, failed) back to GitLab.
  • Artifacts and Caching: If the job configuration includes artifacts, the runner collects the specified files or directories after the script execution finishes and uploads them back to GitLab. If caching is configured, the runner manages downloading and uploading cache dependencies.
  • Job Completion: Once all the scripts have finished executing and artifacts/cache have been handled, the runner reports the final status of the job (success if all scripts exited with a zero status, failure otherwise) to GitLab. The temporary working directory and the execution environment (like the Docker container) are typically cleaned up.

This process ensures that each job runs in isolation and that the results and any required files (artifacts) are sent back to GitLab for review and use by subsequent stages or jobs.