GitHub Enterprise Integration

📘

Note

To use this feature, you need SAP LeanIX Technology Risk and Compliance.

Overview

The GitHub Enterprise integration helps you automatically discover and manage self-built software in your IT landscape using GitOps. This integration captures metadata and simplifies the discovery of self-built software by using manifest files in GitHub. These files describe the properties of self-built software artifacts. This allows developers to operate within the familiar GitHub environment while ensuring that project details are accurately represented and maintained within the architectural landscape, promoting improved oversight and alignment.

If your organization uses a different Source Code Management (SCM) platform, such as Azure, GitLab, or Bitbucket, you can set up self-built discovery by placing a manifest in the root directory of your Git repository. Currently, we do not provide out-of-the-box integrations for other SCM platforms. To learn how to set up self-built discovery using a manifest file, visit Microservice Discovery in Your CI/CD Pipeline.

📘

Note

The integration is only available for GitHub Enterprise Server (self-hosted deployment) and is not supported for GitHub Enterprise Cloud.

Benefits

• Automated discovery: The integration automatically identifies and integrates your self-built software projects from GitHub Enterprise into your SAP LeanIX inventory. This automation saves you time and effort by eliminating the need for manual import of microservices.
• Seamless collaboration: The integration connects to your version control system and uses the workflows your developers already know. This makes it easier for developers to contribute to your architectural practice.
• Enhanced architectural visibility: The integration improves the visibility of your self-built software within your IT landscape. It provides a comprehensive view of your entire architectural landscape, aiding in decision-making.
• Open-source GitHub agent: The SAP LeanIX GitHub agent is an open-source project, which enhances the transparency of the integration. The agent discovers self-built software in self-hosted GitHub Enterprise setups and communicates this information to SAP LeanIX workspaces.

Scope and Limitations

The GitHub Enterprise integration helps you discover microservices by placing a YAML manifest file in the root directory of your repository. This integration does not include:

• Generating and uploading Software Bill of Materials (SBOM). For more information on generating SBOMs, refer to Generating SBOMs.
• Automated discovery of microservices without placing a YAML manifest file in your repository.

Setting Up the Integration

To learn how to set up the integration, see Setting Up the GitHub Enterprise Integration.

Updating 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.

To update the GitHub agent to the latest version, follow these steps:

1. Pull the latest version of the agent ghcr.io/leanix/leanix-github-agent:x.x.x.
2. Redeploy the updated agent.

Viewing Discovered Microservices

On the integration page, you can view discovered microservices and their respective repositories. You can navigate to microservice fact sheets from here. If a repository is linked to a discovered microservice, clicking the repository name takes you to the manifest file. If no microservices are discovered for a repository, clicking the repository name directs you to the repository's root.

Deleting the Integration

If needed, you can delete the GitHub Enterprise integration. To do this, in the upper-right corner of the integration page, click the three-dot icon > Delete Integration. This action will remove the link to GitHub from all microservice fact sheets that were imported through the integration. However, this will not delete or archive any fact sheets, as you may have added some details to them manually. Therefore, you will need to delete these fact sheets yourself if needed.

To identify fact sheets that are no longer connected to GitHub following the deletion of the integration, you can apply a filter to show only those with a GitHub Enterprise external ID set to null. This will help you find and manage all fact sheets that have lost their connection to GitHub due to the deletion of the integration.

To complete the deletion, do the following:

1. Remove the GitHub App from your organization’s settings. For instructions, refer to the GitHub documentation.
2. Delete the deployments from your agent.

Troubleshooting

Here are some common problems and their solutions:

• Authentication errors: While the GitHub App is designed to minimize such issues, you may still encounter authentication errors if a required permission was not selected. You can find these errors in the synchronization log in SAP LeanIX. If this happens, review the permissions you've selected during the setup process to ensure all necessary permissions are granted.
• Errors parsing the manifest file: If there are invalid entries in the manifest file, they appear in the synchronization log in SAP LeanIX. To fix this, check the manifest file to ensure it has the correct structure and syntax.

FAQs

What happens if I delete a leanix.yaml file?

Deleting a leanix.yaml file will unlink the corresponding fact sheet in SAP LeanIX. The external ID for GitHub will be removed, and the fact sheet will no longer be linked to GitHub. However, the fact sheet itself will not be automatically deleted, as it may contain other relevant information. If the fact sheet is no longer needed, you can archive it manually.

What happens if I manually add or overwrite information in fact sheets linked to a manifest file?

The manifest file is considered the source of truth for all the information it contains. Therefore, any manual changes made to fields owned by the integration will be overwritten on the next update to ensure consistency with the manifest file. However, you can manually update fields or relations not managed by the integration.

How do you ensure that two manifest files don't write information to the same fact sheet?

The GitHub integration uses the location of the leanix.yaml file as a unique identifier for the microservice, which is then used to create the external ID in the fact sheet. Therefore, even if you copy an identical manifest to two locations, it will create two separate fact sheets. However, if the name attribute in the manifest is identical, the integration will fail to process the second manifest file, as name in the manifest file corresponds to displayName in SAP LeanIX, which is unique.

I want to restructure a repository with synced leanix.yaml files. What should I consider before doing that?

The location of the manifest file in your repository serves as a unique identifier within SAP LeanIX. If you're planning to restructure a repository and move a leanix.yaml file, you should:

1. Move the leanix.yaml file to your desired new location. For example, if the file used to reside in acme-org/sample-repo/src, you might move it to acme-org/sample-repo/new_sub_directory.

2. Manually update the externalId in the manifest file to point to the old external ID (acme-org/sample-repo/src). This ensures the connection between the fact sheet and the moved leanix.yaml file remains intact.

   YAML

   version: 1
   metadata:
     name: disputes-service-v1
     externalId: acme-org/sample-repo/src
     description: |
       A microservice responsible for payment disputes.
       This service handles payment transaction disputes and is an integral part of our payment ecosystem.