CICD Integration

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.

Jenkins

Hint

LeanIX offers a standard plugin to get started from Jenkins quickly - see https://plugins.jenkins.io/leanix-microservice-intelligence/ for details

For further information please view the installation guide.

Github Actions

Hint

LeanIX offers a standard plugin to get started from Github Actions quickly - see https://github.com/marketplace/actions/leanix-microservice-intelligence for details

For further information please view the installation guide.

Azure DevOps

Connect straight to your Pipelines to receive updates at the stage of your choosing. Each pipeline is treated as a Microservice Fact Sheet, and success/failure statistics are included. See the examples here: https://github.com/leanix-public/leanix-cicd-examples/tree/main/azure-devops

Generic CICD Connector

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

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

Custom Setup

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. If you use one of the supported package managers extract the respective dependency information (see above)

  4. Authenticate using LeanIX authentication mechanisms and receive a bearer token: https://dev.leanix.net/docs/authentication

  5. 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 [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

API documentation is available at API Guide

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.

Custom Data load

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://dev.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 months ago


CICD Integration


Suggested Edits are limited on API Reference Pages

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