leanix-github-agent

About This Project

The SAP LeanIX agent discovers self-built software in self-hosted GitHub Enterprise setups and communicates this information to an SAP LeanIX workspace.

Prerequisites and Installation

Prerequisites

• Docker: The agent is distributed as a Docker image. Docker is required to run it.
• GitHub Enterprise Server: The agent interacts with GitHub Enterprise Server. You need access to a GitHub Enterprise Server instance.
• GitHub App: The agent operates as a GitHub App. You need to create a GitHub App in your GitHub Enterprise Server instance.

Installation

1. Create a GitHub App: Create a new GitHub App in your GitHub Enterprise Server instance. For details, refer to the GitHub documentation.

2. Generate a private key: In your GitHub App settings, generate a private key. For instructions, refer to the GitHub documentation. The agent will use the downloaded PEM file to authenticate with the GitHub Enterprise environment.

3. Install the GitHub App: Install the app on all organizations that the agent should access. For instructions, refer to the GitHub documentation.

4. Configure the agent: The agent requires the following environment variables to run. Pass them to the Docker command when starting the agent.

   • GITHUB_ENTERPRISE_BASE_URL: The base URL of your GitHub Enterprise Server instance.
   • GITHUB_APP_ID: The ID of your GitHub App.
   • PEM_FILE: The path to your GitHub App's PEM file inside the Docker container.
   • WEBHOOK_SECRET: The secret used to validate incoming webhook events from GitHub. (Optional, but recommended. Needs to be set in the GitHub App settings first.)

5. Start the agent: To start the agent, run the following Docker command. Replace the variables in angle brackets with your actual values.

   docker run -p 8000:8080 \
   -v $(pwd)/path/to/your/privateKey.pem:/privateKey.pem \
   -e GITHUB_ENTERPRISE_BASE_URL=<github_enterprise_base_url> \
   -e GITHUB_APP_ID=<github_app_id> \
   -e PEM_FILE=/privateKey.pem \
   -e WEBHOOK_SECRET=<webhook_secret> \
   leanix-github-agent

   This command starts the agent and exposes it on port 8000. The agent starts scanning your organizations and repositories.

6. The container hosts a live service that runs continuously.

   • It provides a health endpoint at /actuator/health, which can be used to monitor the service's health.

Note: The Docker image for the agent is currently unavailable. It will become available for download once a new version is released. Please check the Releases page for updates.

Support and Feedback

We welcome your feedback, feature suggestions, and bug reports via GitHub issues.

Contributing

We encourage contributions to this project. For details on how to contribute, the project structure, and other related information, refer to Contributing.

Reporting Security Issues

If you discover a potential security issue, follow our Security Policy for reporting. Please do not create GitHub issues for security-related matters.

Code of Conduct

We as members, contributors, and leaders pledge to make participation in our community a harassment-free experience for everyone. By participating in this project, you agree to abide by its Code of Conduct at all times.

Licensing

Copyright 2024 SAP SE or an SAP affiliate company and leanix-github-agent contributors. Please see our LICENSE for copyright and license information. Detailed information including third-party components and their licensing/copyright information is available via the REUSE tool.