gitlab-runner-operator

packaged by Chainguard

Chainguard Container for gitlab-runner-operator

gitlab-runner-operator is a Kubernetes/OpenShift operator that manages the lifecycle of GitLab Runner instances via the Runner custom resource.

Chainguard Containers are regularly-updated, secure-by-default container images.

Download this Container Image

For those with access, this container image is available on cgr.dev:

docker pull cgr.dev/ORGANIZATION/gitlab-runner-operator:latest

Be sure to replace the ORGANIZATION placeholder with the name used for your organization's private repository within the Chainguard Registry.

Compatibility Notes

The Chainguard gitlab-runner-operator image is a minimal, distroless replacement for the upstream GitLab Runner Operator image, with the following differences:

• Like all Chainguard Containers, the image contains only the operator binary and its runtime dependencies. It does not include a shell or package manager.
• The image runs as a non-root user (UID 1001) by default.
• The operator binary is installed at /usr/bin/manager, which is also the image entrypoint. A relative /manager symlink mirrors the upstream entrypoint path, so existing manifests and Operator Lifecycle Manager (OLM) bundles continue to work unchanged.
• The runner configuration templates that the operator renders at runtime are installed under /templates, matching the upstream image layout.

The gitlab-runner-operator image manages GitLab Runner instances through the Runner custom resource. It is typically installed through OLM or the upstream config/ manifests; there is no official Helm chart.

The operator's admission webhooks are enabled by default and require TLS serving certificates in the cluster, which are normally provisioned by OLM or cert-manager. When deploying the operator without them, set the ENABLE_WEBHOOKS environment variable to "false" so the manager starts without attempting to serve webhooks. This mirrors upstream operator behavior and is not specific to the Chainguard image.

Prerequisites

To follow the examples in this section, you need the following:

• A running Kubernetes or OpenShift cluster, along with a kubectl client configured to reach it.
• Permission to create cluster-scoped resources, such as custom resource definitions.

Getting Started

The gitlab-runner-operator image is designed to run inside a Kubernetes or OpenShift cluster, where it watches for Runner resources and reconciles them into running GitLab Runner instances.

Begin by registering the Runner custom resource definition (CRD) that the operator reconciles. The following command applies the CRD from the operator's upstream repository:

kubectl apply -f https://gitlab.com/gitlab-org/gl-openshift/gitlab-runner-operator/-/raw/master/config/crd/bases/apps.gitlab.com_runners.yaml

customresourcedefinition.apps.gitlab.com/runners.apps.gitlab.com created

Next, define a namespace, a service account, and a deployment that runs the operator. The following command writes these resources to a file:

cat > gitlab-runner-operator.yaml <<EOF
apiVersion: v1
kind: Namespace
metadata:
  name: gitlab-runner-system
---
apiVersion: v1
kind: ServiceAccount
metadata:
  name: gitlab-runner-operator
  namespace: gitlab-runner-system
---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: gitlab-runner-operator
  namespace: gitlab-runner-system
  labels:
    app.kubernetes.io/name: gitlab-runner-operator
spec:
  replicas: 1
  selector:
    matchLabels:
      app.kubernetes.io/name: gitlab-runner-operator
  template:
    metadata:
      labels:
        app.kubernetes.io/name: gitlab-runner-operator
    spec:
      serviceAccountName: gitlab-runner-operator
      containers:
        - name: manager
          image: cgr.dev/ORGANIZATION/gitlab-runner-operator:latest
          env:
            - name: ENABLE_WEBHOOKS
              value: "false"
EOF

This example omits the role-based access control (RBAC) rules that the operator needs to manage runners in a real cluster. For a production deployment, apply the ServiceAccount, Role, and RoleBinding resources from the upstream config/ manifests or the OLM bundle, then bind them to the operator's service account.

Apply the manifest to your cluster:

kubectl apply -f gitlab-runner-operator.yaml

namespace/gitlab-runner-system created
serviceaccount/gitlab-runner-operator created
deployment.apps/gitlab-runner-operator created

Once the deployment is available, confirm that the operator has started and is reconciling resources by checking its logs:

kubectl logs -n gitlab-runner-system -l app.kubernetes.io/name=gitlab-runner-operator

INFO    controller-runtime.metrics      Serving metrics server  {"bindAddress": ":8080"}
INFO    Starting Controller     {"controller": "runner"}
INFO    Starting workers        {"controller": "runner", "worker count": 1}

With the operator running, you can register a runner. The following command creates a secret that holds the GitLab registration token, along with a Runner resource that references it:

cat > runner.yaml <<EOF
apiVersion: v1
kind: Secret
metadata:
  name: gitlab-runner-secret
  namespace: gitlab-runner-system
stringData:
  runner-registration-token: REPLACE_WITH_YOUR_TOKEN
---
apiVersion: apps.gitlab.com/v1beta2
kind: Runner
metadata:
  name: example-runner
  namespace: gitlab-runner-system
spec:
  gitlabUrl: https://gitlab.example.com
  token: gitlab-runner-secret
EOF

Apply the runner definition:

kubectl apply -f runner.yaml

secret/gitlab-runner-secret created
runner.apps.gitlab.com/example-runner created

The operator renders the runner configuration into a ConfigMap named after the Runner resource, then deploys a GitLab Runner instance that registers with the GitLab URL you provided.

Configuration

The gitlab-runner-operator image uses the same configuration interface as the upstream operator, which is driven through command-line flags and environment variables on the manager container.

As an example, the deployment above disables the admission webhooks by setting the ENABLE_WEBHOOKS environment variable to "false". The webhooks validate Runner resources but require TLS certificates to be provisioned in the cluster, so disabling them is a convenient way to evaluate the operator before you configure certificate management. In a production cluster where certificates are available, omit this variable to benefit from webhook validation.

For the full set of supported flags, environment variables, and Runner fields, refer to the upstream GitLab Runner Operator documentation.

Documentation and Resources

• GitLab Runner Operator documentation
• GitLab Runner documentation
• Getting Started with Chainguard Containers

What are Chainguard Containers?

Chainguard's free tier of Starter container images are built with Wolfi, our minimal Linux undistro.

All other Chainguard Containers are built with Chainguard OS, Chainguard's minimal Linux operating system designed to produce container images that meet the requirements of a more secure software supply chain.

The main features of Chainguard Containers include:

• Minimal design, without unnecessary software bloat
• Daily builds to ensure container images are up-to-date with available security patches
• High quality build-time SBOMs attesting to the provenance of all artifacts within the image
• Verifiable signatures provided by Sigstore
• Reproducible builds with Cosign and apko (read more about reproducibility)

For cases where you need container images with shells and package managers to build or debug, most Chainguard Containers come paired with a development, or -dev, variant.

In all other cases, including Chainguard Containers tagged as :latest or with a specific version number, the container images include only an open-source application and its runtime dependencies. These minimal container images typically do not contain a shell or package manager.

Although the -dev container image variants have similar security features as their more minimal versions, they include additional software that is typically not necessary in production environments. We recommend using multi-stage builds to copy artifacts from the -dev variant into a more minimal production image.

Need additional packages?

To improve security, Chainguard Containers include only essential dependencies. Need more packages? Chainguard customers can use Custom Assembly to add packages, either through the Console, chainctl, or API.

To use Custom Assembly in the Chainguard Console: navigate to the image you'd like to customize in your Organization's list of images, and click on the Customize image button at the top of the page.

Learn More

Refer to our Chainguard Containers documentation on Chainguard Academy. Chainguard also offers VMs and Libraries — contact us for access.

Trademarks

This software listing is packaged by Chainguard. The trademarks set forth in this offering are owned by their respective companies, and use of them does not imply any affiliation, sponsorship, or endorsement by such companies.