Quick Setup of GitLab Runner on puzl.cloud

In just a few steps, you'll have a GitLab Runner up and running. Let's get started!

Step 1: Setting Up the Integration

The first thing you need is to set up the GitLab Pipelines Integration. This will connect your GitLab instance with the Puzl.

Cloud Dashboard

1. Log in to the CI Runners dashboard.
2. Navigate to the GitLab Integrations section.
3. Click on "Add New Integration", fill in the URL of your GitLab instance and submit the form.

kubectl

Here and in other guides, we will use cross-platform kubectl CLI util to access the declarative Kubernetes API provided by Puzl. An instruction on how to install kubectl on your local machine is available in the separate user manual on integrations page of your CI Runners dashboard.

Once you have kubectl set up, please follow the steps below.

1. Create a YAML configuration file named my-first-integration.yaml:

apiVersion: gitlab-pipelines.svcs.puzl.cloud/v1
kind: GitLabPipelinesIntegration
metadata:
  name: my-first-integration
spec:
  # Replace it with your GitLab host if using self-hosted GitLab
  gitlabUrl: https://gitlab.com

2. Apply this configuration.

kubectl apply -f my-first-integration.yaml

Once applied, the Integration will automatically create an isolated namespace, where you can manage your GitLab runners.

Step 2: Register a New Runner in your GitLab

Step 3: Setting up the Runner

With the Integration in place, you can now request a new GitLab runner.

Cloud Dashboard

1. Navigate to the GitLab Runners section in the Puzl Cloud Dashboard.
2. Click on "Create New Runner" and fill in the required fields.

kubectl

1. Retrieve the name of the namespace, previously created by your Integration.

kubectl get glpintegration my-first-integration -o=jsonpath='{.spec.claimNamespaceRef}'

2. Create a YAML configuration file named my-first-runner.yaml. Here is the minimalistic configuration with the required fields only:

apiVersion: gitlab-pipelines.svcs.puzl.cloud/v1
kind: GitLabRunnerClaim
metadata:
  # Replace <Your_Integration_claimNamespaceRef> with the value retrieved in the previous step.
  namespace: <Your_Integration_claimNamespaceRef>
  name: my-first-runner

spec:
  gitlab:
    token: <Your-GitLab-Token>

    # Tags are deprecated. Set up tags here only if you have GitLab v15 or earlier.
    tags:
      # Replace <Tag-1> and <Tag-2> with the required tags. Add more tags as needed.
      - <Tag-1>
      - <Tag-2>

3. Apply this configuration.

kubectl apply -f my-first-runner.yaml

Step 4: Checking Runner Status

After creating the runner, you'll want to monitor the status of your runner to know when it's operational and ready to process GitLab pipeline jobs.

Cloud Dashboard

1. Navigate to the GitLab Runners section in the Puzl Cloud Dashboard.
2. Find the runner you have just created. The status will be displayed alongside and should be Running.

kubectl

Execute the following command to retrieve the status of your GitLabRunnerClaim.

kubectl get glpclaim -n <Your_Integration_claimNamespaceRef> my-first-runner

If the returned status is Ready, your runner is operational and is serving GitLab pipeline jobs associated with it. Typically, transitioning to the Ready phase takes less than a minute after the GitLabRunnerClaim creation.

If the claim is not Ready, you might want to wait a couple of minutes or check its status for any potential issues.

Conclusion

You're all set! Your GitLab runner is configured and ready to serve dozens of GitLab pipeline jobs in parallel.

To explore all available runner settings and gain a detailed understanding of the runner's lifecycle on Puzl, including its various phases and statuses, refer to GitLabRunnerClaim docs.