GitLab System Administration - Hands-on Lab: Configure GitLab Runners

This Hands-On Guide walks you through installing and managing a GitLab Runner on a virtual machine.

Estimated time to complete: 40 minutes

Objectives

The objective of this lab is to demonstrate how to create and register a GitLab Runner on a server. For more information about GitLab Runners, click here.

Task A. Install the gitlab-runner package

  1. Use your assigned IP address and SSH key file to log into your GitLab Runner server (not your Omnibus server).

    ssh -i <YOUR_ASSIGNED_SSH_KEYFILE> root@<YOUR_RUNNER_SERVER_PUBLIC_IP>
    
  2. If your system displays an authentication warning, type yes and press Enter

  3. Add the GitLab Runner installation repository.

    curl -L "https://packages.gitlab.com/install/repositories/runner/gitlab-runner/script.deb.sh" | sudo bash
    
  4. Install the GitLab Runner agent.

    sudo apt-get install -y gitlab-runner
    
  5. Once the install completes, check that the service is running.

    sudo gitlab-runner status
    

Task B. Register a runner with GitLab

  1. Sign into your GitLab instance with a web browser and select Admin Area from the left sidebar.

  2. In the left sidebar, under CI/CD, select Runners.

  3. Select New instance runner.

  4. In the Tags section, select Run untagged jobs.

    This will allow the runner to pick up any jobs rather than just jobs with specific tags.

  5. Leave all other options as default and select Create runner.

  6. Ensure that Linux is selected as the Operating system for the runner.

  7. Copy the command in Step 1, and add sudo in front of the command. Run it in your command prompt.

  8. The command will first prompt you for your GitLab instance URL. Verify that this URL matches your GitLab instance, then press Enter

  9. Enter any appropriate name for your runner.

  10. When you are prompted for an executor, type shell.

    A shell executor will run jobs using your instance’s shell. For more information about executors, check the documentation.

  11. Run sudo gitlab-runner list to verify the runner after registration.

  12. Return to your web browser and select View runners. Verify the runner you registered appears in the list and shows as online.

Task C. Test the runner with a CI/CD pipeline

  1. Navigate back to the homepage of your GitLab instance by selecting the GitLab icon at the top of the left sidebar.

  2. Select Create a project.

  3. Select Create blank project.

  4. Enter CICD Test as the project name.

  5. In the Project URL, select root from the namespace dropdown.

  6. Leave all other settings as they are and click Create project.

  7. In the middle of the project landing page, under the project title, select the + dropdown. Select New file.

  8. On the new file page, enter .gitlab-ci.yml as the file name.

  9. Paste the following code into the body of the file.

    stages:
      - build
      - test
    
    build_app:
      stage: build
      script:
        - echo "The build stage requires at least one job"
    
    test_app:
      stage: test
      script:
        - echo "The test stage requires at least one job"
    
  10. Select Commit changes.

  11. In the left sidebar, select Build > Pipelines.

  12. Select the pipeline status (it should say passed).

  13. Click into each of the build_app and test_app jobs to see the job logs and commands that were executed on the runner.

Lab Guide Complete

You have completed this lab exercise. You can view the other lab guides for this course.

Suggestions?

If you’d like to suggest changes to the GitLab System Admin Hands-on Guide, please submit them via merge request.