Connecting into your CI/CD pipeline allows developers to utilize existing tooling for their automatic documentation. Instead of tediously open a Web UI after a deployment, they can do all their changes in their IDE - and rely on LeanIX Microservice Intelligence to capture changes, make them transparent, and notify others.

Synchronized Data

The CICD connector captures deployment-, microservice- and library-related information at the time of deployment through a CD-pipeline. Thereby the connector provides an API to capture individual deployments of a specific microservice. The API can either be leveraged directly or through one of our plugins.

There are three essential part to the data input:

  1. Microservice documentation
  2. Deployment information
  3. Library information

Microservice Documentation

Currently, we have two options to add the Microservice documentation information via the CICD connector

Option 1 - Static lx-manifest.yaml
This is a yaml-file added on the root level of each repository that you want to recognize as a microservice. A lx-manifest.yaml follows a fixed base structure but can also be flexibly advanced with custom data.

A simple example file might look like this:

id: cicd-connector-v2
name: cicd-connector-v2
description: CI/CD revamped
self: https://github.com/leanix/cicd-connector-v2/blob/main/lx-manifest.yml
owner: [email protected]
teams:
  - cider
products:
  - leanix-mi
links:
  - name: vcs
    url: https://github.com/leanix/cicd-connector-v2

The support key-value pairs for the manifest available can be found below.

Name
Description
Required
Correctness Criteria
Automatic detection at build time possible?

id

Identifies the microservice

yes

non-empty string

Cannot contain '/' for valid deployment ID structure

Yes (take repo name as id)

name

Name of the microservice

yes

non-empty string

Yes (take repo name unless changed in MI)

description

Description of the MS

no

non-empty string

No

self

URL of the metadata file. Which will give the information of the root of the project in VCS

yes

Url

n/a - since file doesn’t exist

domains

List of domain Ids from the MI workspace

no

non-empty list of strings

No

teams

List of team Ids from the MI workspace. If team Id is not present integration api would raise warnings.

no

non-empty list of strings

No

products

List of product Ids from MI workspace

no

non-empty list of strings

No

links

Links to other resources (e.g. Git Repository, API Documentation)

links:
  - name: ''
    url: ''

no

Urls,
data structure as agreed on the metadata

No

owner

no

Email Address

No

tags

List of tags to be checked for every deployment and updated. Tags should always be part of a leanix tag group.

tags:
  - tag-group: Environment
    tag-name: Staging

no

non-empty list of key value pairs

No universal tagging mechanism in place. (For individual data points, possible)

lifecycle

lifecycle:
  planned: 2021-11-01
  early-access: 2021-11-01

no

No

Hint

If you choose to add custom data on top, additional Integration API processors need to be added to your workspace in order to map the custom data into the workspace. Please view the section Custom Data Load for more information.

Option 2 - Dynamic Microservice data
If you have data around your microservice already available at build time and you don’t want to add a yaml to every repository there is an option to pass the Id of the microservice as part of the API request. This will create/update a microservice fact sheet with that specific ID

Deployment Information

Standard deployment information will be:

  • the current deployment version
  • the current deployment stage
  • the date and time of deployment

This information should be passed to the API (either through plugin or custom call). In the case of a custom API call any other key-value pairs could be added to the body, which would then result into custom data that can be loaded into the deployment fact sheet.

Hint

If you choose to add custom data on top, additional Integration API processors need to be added to your workspace in order to map the custom data into the workspace. Please view the section Custom Data Load for more information.

Library information

For projects using the package managers:

  • NPM
  • Maven
  • Gradle
  • NuGet

a dependencies file can be extracted and sent to the CICD connector, in order to create Library factsheets and link them to the respective microservices and deployments.

Plugins take care of the extraction.

Hint

Setup

When setting up the CI/CD connector we recommend to always start with a plugin integration, if a plugin is avaible for your platform. Current we support:

A custom setup always depends on the capabilities that the pipeline provider has, but usually there is an option to execute a bash script. For a basic setup follow these steps:

  1. Create an lx-manifest according to the specifications Client Metadata file documentation or add logic to pass the microservice id to the API call. The very minimum information required in both scenarios is a microservice id.

  2. Create two env variables that capture the deployment stage and version at build time. Often both of these information points are already available in the pipeline and can simply be referenced.

  3. (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 MI 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

For NuGet run:

dotnet tool run dotnet-project-licenses -p false -o --outfile licenses.json -j -i /path/to/csproj-directory

Attention

NuGet projects are automatically detected only by our out-of-box Azure pipeline's plugin solution

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.

  1. Authenticate using LeanIX authentication mechanisms and receive a bearer token: https://docs-eas.leanix.net/docs/authentication
curl --request POST \
  --url https://<host>/services/mtm/v1/oauth2/token \
  -u apitoken:JqcSfeB7sO3Bd9dEDcSOXfjs6G6ORCsT6G9fBHCc \
  --data grant_type=client_credentials
  1. Compile all of the above data into POST /deployment request to the CICD connector API.
curl -X POST \
  -H 'Cache-Control: no-cache' \
  -H 'Authorization: Bearer <auth>' \
  -H 'Content-Type: multipart/form-data' \
  -F manifest=@<abosolute path to manifest file> \
  -F dependencies=@<abosolute path to dependencies file> \
  -F 'data={
  "version": "1.0.0",
  "stage": "dev",
  "dependencyManager": "MAVEN"
}' \
  https://<host>/services/cicd-connector/v2/deployment

API documentation is available at API Guide
Swagger Docs: Swagger

Attention

We are using a multipart/form-data request, which makes the call a bit more complex. Some development tools such as Postman experience difficulties to send a properly formatted request right out of their client. Therefore we recommend using cUrl for development and testing.

Customization options

Custom data can be added in two places:

  • the lx-manifest.yml (as key-value attributes)
  • towards the bottom of the deployment, data object on the request body (ad key-value attributes)

The connector doesn’t touch or modify this data. It is merely passed through to the Integration API.

In order to process this data correctly, you need to add a custom processor set.

Please do not change the base processors added to the workspace by the connector. These will be overwritten automatically by the connector and all your changes will be lost.

Instead, just create a custom processor set and add them to the Integration API execution group by adding this snippet to your processor file:

"executionGroups": [
        "miCiCd"
    ]

The integration API will pick up your processors and merge them with the base processors at execution time. Make sure to set the Integration API run number accordingly.

For more information on the execution groups visit: https://docs-eas.leanix.net/docs/integration-api#section-grouped-execution-of-multiple-integration-api-configurations

Attention

The base processors leverage a deletion scope and Integration API cannot merge deletion scopes. Therefore it is not possible to add any custom deletion scope at this point in time.

The custom processors should also use the processing mode full as do the base processors.

Custom Options

The Integration API gives you great flexibility to update the mapping of metadata information to LeanIX Fact Sheets and Attributes without redeployment and control via the sync log. It allows you e.g. to easily include time-related data in an already existing Integration API call (e.g. combined with the metadata) or in an independent Integration API call.

A sample tutorial with a beta endpoint wrapping the Integration API can be found here: https://github.com/leanix-public/leanix-cicd-examples

Updated 2 days ago


CI/CD


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.