Skip to main content

Gitlab Integration for Self-Hosted Runners on a VM

This section describes how to configure Defakto to provide SPIFFE identities to a Gitlab Pipeline.

In this guide we are going to use a self-hosted Gitlab Runner using the Docker executor and run Gitlab on a Linux VM.

Setup Gitlab​

Follow Official Gitlab Documentation to setup Gitlab for your Linux distribution.

Run a Defakto Agent​

First create a new CI/CD profile on Defakto specifying the URL for your Gitlab deployment as the JWT issuer. For example, using Defakto CLI:

spirlctl ci-cd profile create my-gitlab --issuer $GITLAB_ISSUER_URL

Then add a new node group to Defakto-managed trust domain

spirlctl node-group add $NODE_GROUP_NAME --trust-domain $TRUST_DOMAIN_NAME

Finally, link the node-group with the CI/CD Profile:

spirlctl ci-cd profile link create $NODE_GROUP_NAME my-gitlab --trust-domain $TRUST_DOMAIN_NAME

Install the spirl-agent using the configuration file and key generated by the previous command. See how to install the agent in Linux or using Docker.

Setup a self-hosted Docker Gitlab Runner​

  1. From the Gitlab UI select Admin>Instance Runners>... and copy the registration token.

  2. Install the Gitlab Runner CLI.

  3. Register a runner and note the path to the runner configuration file provided:

    sudo gitlab-runner register \
      --url "$GITLAB_URL" \
      --registration-token "$RUNNER_TOKEN" \
      --description "test-runner" \
      --executor "docker" \
      --docker-image ubuntu \
      --docker-volumes '/var/run/spirl/sockets:/var/run/spirl/sockets'

  4. Run the registered runner using the configuration file created in the previous step:

    sudo gitlab-runner run -c $CONFIG_FILE

Create a Gitlab Pipeline​

Navigate to the Gitlab UI and set up a pipeline using the following steps:

  1. Create a new project.
  2. Create a new pipeline in the project.
  3. Configure the pipeline using the following .gitlab-ci.yml file: 
    stages:
      - authenticate
      - run

    authenticate:
        stage: authenticate
        image:
            name: ghcr.io/spirl/spiffecli:v1.1.0
            entrypoint: [""]
        script:
            - /ko-app/spiffecli get jwt-svid --spiffe-endpoint-socket unix:///var/run/spirl/sockets/agent.sock --audiences http://example.com --identity-exchange-token ${GITLAB_OIDC_TOKEN} --filename spiffe-jwt.json
        id_tokens:
            GITLAB_OIDC_TOKEN:
                aud: https://spirl.com
        artifacts:
            paths:
                - spiffe-jwt.json

    run:
        stage: run
        image:
            name: ubuntu
            entrypoint: [""]
        script:
            - apt-get update && apt-get install -y jq
            - cat spiffe-jwt.json | jq -R 'split(".") | .[1] | @base64d | fromjson'
        dependencies:
            - authenticate
  4. Run the pipeline and see the SPIFFE ID for the job.