Setting Up the GitHub Enterprise Integration

To set up the GitHub Enterprise integration, deploy an agent-based setup within your infrastructure. This agent, provided as a Docker container, can be deployed on-premises, such as on a Kubernetes cluster. The agent continuously syncs changes from the discovered manifest files (leanix.yaml) in GitHub to your SAP LeanIX workspace. This ensures your workspace is always up-to-date with the latest changes. To authenticate and facilitate this process, the agent requires a GitHub App. To learn more about GitHub Apps, refer to the GitHub documentation.

📘

Note

You can configure the integration with a single GitHub instance. This instance can be associated with multiple organizations.

Prerequisites

• In SAP LeanIX:
  • Get admin access to your workspace.
  • Ensure that the workspace is provisioned for self-built software discovery. For details, see Workspace Setup for Self-Built Software Discovery.
  • Create a technical user with admin permissions. Learn how in Technical Users.
• Get admin permissions for your organization on GitHub. This is necessary to install and manage the GitHub App.
• Coordinate with the relevant stakeholders in your organization to deploy the on-premise GitHub agent on your infrastructure. They will also need to provide the URL where the agent is accessible within your network for the GitHub App creation.

Step 1: Create a GitHub App

Creating a GitHub App requires a valid URL for sending webhook events. This URL must correspond to the network address of the SAP LeanIX agent, which will look like https://host:port after deployment. The agent relies on receiving updates from GitHub to function correctly. These updates are sent to the provided URL.

If you're unsure how to obtain a stable URL for the deployed agent, consult with your platform engineering or DevOps team. This step is crucial to ensure the smooth operation of the integration.

To create a GitHub App, follow these steps:

1. In the administration area of SAP LeanIX, navigate to the Integrations section, then click Add Integration.

2. On the page listing available integrations, locate the GitHub Enterprise integration, then click Configure.

   

3. On the integration configuration page, enter the base URL of your GitHub instance (for example, https://leanix-github.com) and the network address where you plan to deploy the agent (for example, https://host:port). Click Create GitHub App.

   

4. In GitHub, generate a private key and save it. This key, along with the GitHub App ID, will be required when deploying the agent.

   Configuration details are prefilled based on the information provided in the previous steps. For details on which events the agent needs permission to listen to, refer to GitHub App Permissions.

   

5. In GitHub, get the GitHub App ID in Settings > Developer settings > GitHub Apps > {Your GitHub App} > General.

   

6. Ensure that the GitHub App can be installed on any account in your GitHub instance.

   

   Alternatively, you can adjust this setting after creating the app in Settings > Developer settings > GitHub Apps > {Your GitHub App} > Advanced > Make public.

   

Step 2: Deploy the SAP LeanIX Agent

After you've set up a GitHub App, deploy the SAP LeanIX agent using the docker-compose code available on the configuration page in SAP LeanIX. For details on the code and environment variables, see Code for Deploying the SAP LeanIX Agent.

For a reliable and consistent operation, we suggest deploying the container using a container orchestration platform such as Kubernetes. This is crucial as GitHub expects the webhook receiver (the agent) to respond within 10 seconds of receiving an event, and will terminate the connection if it doesn't. For details, refer to the GitHub documentation.

For local testing, you can use docker-compose and a tunneling tool like ngrok to redirect traffic to your local setup.

👍

Recommendation

To monitor the agent's status and ensure it's running properly, use the health route host:port/actuator/health.

Step 3: Install the GitHub App

After creating a GitHub App and deploying the agent, the next step is to install the GitHub App on the relevant GitHub organizations. This grants the SAP LeanIX agent access to these organizations.

You can install the app in one of the following ways:

• From the integration page in SAP LeanIX: Here, you can find a KPI indicating how many organizations are currently covered by the agent. To install the app on more organizations, click on the relevant link.

  

  You're redirected to the installation page in GitHub.

  

• In the GitHub App settings: You can directly navigate to this page by going to https://{host url of your GitHub instance}/settings/apps/{name of the created GitHub app}. This will take you to the settings page of the GitHub App you created, where you can manage its installation across your organizations.

Step 4: Add Manifest Files to Projects

Manifest files, specifically leanix.yaml files, are essential tools in the config-as-code practice. They enable you to describe and discover microservices from GitHub in SAP LeanIX. Place leanix.yaml files in the projects that correspond to the microservice or software artifact you want to describe. One manifest file is used to describe one microservice.

To view the structure and schema of the leanix.yaml file, see Manifest File and Schema.

When configuring the manifest file, you can start with basic elements first (such as name and description) and then gradually evolve your governance to include more aspects (like linking to teams). Any changes made to the YAML file will be reflected in SAP LeanIX in near real-time.

For monorepos, where multiple deployed microservices are contained in a single repository, you can place the leanix.yaml file in the directories where a deployed service resides. The integration will find and process them accordingly. Here’s an example configuration:

backend
  Dockerfile
  leanix.yaml
  src
    main.py
    requirements.txt
frontend
  Dockerfile
  leanix.yaml
  package.json
  src
    index.js
    ...

Step 5: Monitor and Manage the Integration

After setting up the integration, you can check the integration status at the top of the page. Here, you can find the deployed version of the GitHub agent. If the version appears in red, this indicates that a more recent version is available for update.

The following metrics provide an integration summary:

• Microservices Discovered: This shows the number of valid manifest files in connected repositories. You can open a boilerplate manifest file, modify it as needed, and add it to your repository to discover more microservices.
• GitHub Organizations: This indicates the number of organizations where the GitHub App is installed, along with the total number of organizations. You can navigate to GitHub from here to install the GitHub App on other organizations.
• Sync Errors: Displays the number of errors that occurred in the last seven days. From here, you can navigate to synchronization logs for the integration.

Update the Agent Version

We periodically release new versions of the SAP LeanIX GitHub agent to ensure optimal performance. The currently deployed version is displayed at the top of the GitHub integration page. If a new version becomes available, you'll see a notification.

For more information, see Updating the Agent Version.