GitLab

GitLab can be easily integrated using the provided CI/CD REST endpoint.

Setup

The CICD integration runs two steps to send the respective data to your VSM workspace:

• it executes a command based on your package manager to generate a dependency file
• it takes the dependency file and your lx-manifest.yml and POSTs both to our CICD API

In the following we will do the same steps using a simple script that can be executed in your GitLab pipeline during the execution of your build job.

Step 1: Add the Microservice documentation to your repository

Before we start on the pipeline setup we need to make sure that the repositories that are being built from your pipeline have the lx-manifest.yml in place.
This file serves as an entry point to create a simple microservice documentation through your development teams.
Make sure the file is added to the root of every repository (or at least that the path is the same across all repositories) so that a reference later on is easily established.

Step 2: Locate the right job in your GitLab pipeline

GitLab pipelines are structured into jobs that run for specific stages of the pipeline (e.g. production, development, testing).
Think about what stage of your pipeline you want to document as a deployment into VSM. We recommend that you should start with the production stage and add other stages later on. This way you will document at least all the deployments to production and understand what services are currently deployed into production in a certain way.
Once the stage is determined you can either add a new job to this stage or pick a job that we will edit.

Step 3: Create an environment variable with the version of your deployment

In order to distinguish different deployments of the same service we use a version parameter that is passed through the CICD API call. This version could be a deployment version that already exists, the version of the image you are deploying or a simple git sha.

Make sure the version is present in your job as an environment variable.

Step 4: (Optional) Execute the dependency calculation in your job

The CICD integration can parse dependency files from NPM and Maven and create Library fact sheets out of them for your VSM workspace. Run the respective command below in your job.

For NPM run:

license-checker --json > /path/to/dependencies.json

For Maven run:

mvn license:download-licenses

Please note down the paths that the resulting file is sent to, as we will need these to reference the file in our API call later.

Step 5: Authorize against LeanIX APIs in your job

In order to make the call to our CICD API, you need to authenticate against our APIs. For this please create a technical user token from the administration section of your workspace. Please add the call below to your job using the right host.

📘

Find your host

The host is the first part of the URL shown when you enter your VSM workspace (e.g. app.leanix.net)

curl --request POST \
  --url https://<host>/services/mtm/v1/oauth2/token \
  -u apitoken:JqcSfeB7sO3Bd9dEDcSOXfjs6G6ORCsT6G9fBHCc \
  --data grant_type=client_credentials

The call will send back a bearer token that is valid for your session (1 hour) and can be used for the further API calls.

Step 6: Call the CICD API from your job

Last we pull all the results from the previous step together and send everything to /deployment on the CICD API.

For this please execute the following shell script with:

• auth = your bearer session token
• manifest = the absolute path to your lx-manifest file
• (Optional) dependencies = the absolute path to the dependencies file generated in step 3
• version = the version (passed as an environment variable)
• stage = the stage of your runner
• dependencyManager = NPM, MAVEN or GRADLE

curl -X POST \
  -H 'Cache-Control: no-cache' \
  -H 'Authorization: Bearer <auth>'\
  -H 'Content-Type: multipart/form-data' \
  -F [email protected]<abosolute path to manifest file> \
  -F [email protected]<abosolute path to dependencies file> \
  -F 'data={
  "version": "1.0.0",
  "stage": "dev",
  "dependencyManager": "MAVEN"
}' \
  https://<host>/services/cicd-connector/v2/deployment

The API will respond with an Integration API run ID that can be used to understand the status of the data load and receive logs upon completion. For more information check our integration API documentation.