As part of our CI/CD integration, we provide a native plugin for GitHub Actions. You can add our build step from the GitHub Actions Marketplace directly into your pipeline. The full setup will be done from there. Connecting to your CI/CD pipeline allows developers to utilize existing tooling for their automatic documentation. Instead of tediously opening a Web UI after a deployment, they can do all their changes in their IDE - and rely on LeanIX Value Stream Management to capture changes, make them transparent, and notify others.

The data that is synchronized is completely the same as for the generic CI/CD integration. If you, later on, wish to add additional information you can find our customization options here.

Setup

Prerequisites

manifest.yml file

Place the manifest.yml file containing the correct information about your project in your project repository. You can use any path you want, this is passed to the action as an input parameter.

Secret LeanIX API token

In the "Settings" -> "Secrets" -> "Actions secrets" area of ​​the GitHub project for which the action is used, a secret must be created, the value of which is a valid LeanIX Technical User Admin token for the host that is used in the action.

Refer to LeanIX authentication mechanisms and receive a bearer token.

👍

More information on GitHub repository secrets

Refer to the official GitHub documentation for more details.

Configuration

Adding a workflow to your GitHub repository

If you are logged into GitHub and are on the page of your repository, you will see a bar with tabs below the repository name, one of which is titled "Actions".

Under this tab you will find the workflows that are specified in your project. A workflow could be described as the collection of jobs, steps in jobs and actions (like the LeanIX Action) in steps.

If you want to add the LeanIX action to a workflow, you can use the example workflow code listed below. Just add a file with a valid workflow yml-file to your repository unter the path .github/workflows/ , for example a file containing the workflow below under .github/workflows/test_leanix_action.yml .

👍

GitHub workflows

More information on creating workflows for a project and adding actions to workflows can be found at https://docs.github.com/en/actions/learn-github-actions/introduction-to-github-actions#create-an-example-workflow

Monitoring of the action

The monitoring of the workflows and thus also that of the actions belonging to your project also takes place under the tab "actions". There you can see the output of every step of your workflow. As part of a step, the LeanIX action will generate meaningful messages both in the event of successful execution and in the event of an error, which you can use to understand what happened during the execution of the action.

Example workflow

The input parameters used in the example are explained in more detail in the "Inputs" section. The workflow, including the action, is triggered when you push a new commit to the repository.

name: leanix-action-test

on:
  push:

env:
  HOST: app.leanix.net
  LEANIX_MANIFEST_PATH: /lx-manifest.yml
  DEPENDENCY_MANAGER: NPM
  STAGE: test
  VERSION: 2.2.0
  ALLOW_FAILURE: true


jobs:
  leanix_test_job:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/[email protected]
      - name: LeanIX Microservice Intelligence
        uses: leanix/[email protected]
        id: LIXVSM
        with:
          host: ${{ env.HOST }}
          api-token: ${{ secrets.LEANIX_API_TOKEN }}
          manifest-path: ${{ env.LEANIX_MANIFEST_PATH }}
          dependency-manager: ${{ env.DEPENDENCY_MANAGER }}
          stage: ${{ env.STAGE }}
          version: ${{ env.VERSION }}
          allow-failure: ${{ env.ALLOW_FAILURE }}

🚧

Information:

Follow the code above exactly / paste it to avoid issues such as indentation levels when creating your file.

Environment variables

In the example workflow, various environment variables are initialized in the "env:" area. This allows you to reuse the values ​​in the jobs of your workflow. Of course, every value in the "with:" area of ​​the github action can also be set directly. In the example, the values ​​of the environment variables are assigned to the input parameters of the LeanIX Action in this area. In order to meet the security standards, the API token must not be set in clear text in the workflow area, but the way described above must be chosen.

Mandatory and optional definitions

The steps and assignments carried out under "jobs:" are necessary for the use of the LeanIX Action. In addition to the environment variables/input parameters to be set correctly, you can choose the following values ​​yourself:

• "uses: leanix/[email protected]": Here you can choose which version of the LeanIX action you want to use.
• "id: LIXVSM": This value is optional, here you can choose any ID for the LeanIX step in order to reference it elsewhere. For more information, see also https://docs.github.com/en/actions/reference/workflow-syntax-for-github-actions#jobsjob_idstepsid

Input

Options

Fetching dependencies from a custom Maven server

📘

Follow Maven official documentation for more details about the settings file

Following is an example maven settings file present in a GitHub repository.

<settings xmlns="http://maven.apache.org/SETTINGS/1.0.0"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.0.0 https://maven.apache.org/xsd/settings-1.0.0.xsd">
    <servers>
        <server>
            <id>custom-server</id>
            <username>${env.MAVEN_USERNAME}</username>
            <password>${env.MAVEN_PASSWORD}</password>
        </server>
    </servers>
<!--...-->
</settings>

Following is the corresponding GitHub action file to use a custom Maven settings file.

name: leanix-action-test

on:
  push:

env:
  HOST: app.leanix.net
  LEANIX_MANIFEST_PATH: /lx-manifest.yml
  DEPENDENCY_MANAGER: MAVEN
  SETTING_FILE: settings.xml
  MAVEN_USERNAME: ${{ secrets.MAVEN_USERNAME }}
  MAVEN_PASSWORD: ${{ secrets.MAVEN_PASSWORD }}
  STAGE: test
  VERSION: 2.2.0
  ALLOW_FAILURE: true


  jobs:
    leanix_test_job:
      runs-on: ubuntu-latest
      steps:
        - name: Checkout
          uses: actions/[email protected]
        - name: LeanIX Value Stream Management
          uses: leanix/[email protected]
          id: LIXVSM
          with:
            host: ${{ env.HOST }}
            api-token: ${{ secrets.LEANIX_API_TOKEN }}
            manifest-path: ${{ env.LEANIX_MANIFEST_PATH }}
            dependency-manager: ${{ env.DEPENDENCY_MANAGER }}
            maven-settings-path: ${{ env.SETTING_FILE }}
            stage: ${{ env.STAGE }}
            version: ${{ env.VERSION }}
            allow-failure: ${{ env.ALLOW_FAILURE }}

🚧

Plugin Limitation

In case of failure to read the private dependencies, the plugin currently does not support the feature to only read the public dependencies skipping the private ones.