Service Architecture Intelligence with GitHub Enterprise (on-premises)

Create and configure a GitHub App

In your GHE instance, navigate to Settings → Developer Settings → GitHub Apps → New GitHub App. For detailed instructions on creating a GitHub App, refer to the GitHub documentation on registering a GitHub App.

Configure permissions

Configure app permissions accurately to ensure seamless data fetching during the initial sync and efficient listening to webhook events thereafter. App permissions define the scope of access that the application has to various repository and organizational resources on GitHub. By tailoring these permissions, you can enhance security, ensuring that the application only accesses the necessary data while minimizing exposure. Proper configuration facilitates smooth initial data synchronization and reliable event handling, optimizing the application's integration with GitHub's ecosystem.

For detailed guidance on GitHub App permissions, refer to the GitHub documentation on setting permissions for GitHub Apps.

Required repository permissions

Configure the following repository-level permissions exactly as shown to enable data synchronization:

• Administration: Read-only ✓
• Checks: Read-only ✓
• Commit statuses: Selected ✓
• Contents: Selected ✓
• Custom properties: Selected ✓
• Deployments: Read-only ✓
• Metadata: Read-only (mandatory) ✓
• Pull requests: Selected ✓
• Webhooks: Read-only ✓

Required organization permissions

Configure the following organization-level permissions exactly as shown:

• Administration: Read-only ✓
• Custom organization roles: Read-only ✓
• Custom properties: Read-only ✓
• Custom repository roles: Read-only ✓
• Events: Read-only ✓
• Members: Read-only ✓
• Webhooks: Read-only ✓

Webhook event subscriptions

Select the following webhook events exactly as shown for real-time synchronization and monitoring:

✓ Select these events:

• check_run - Check run status updates
• check_suite - Check suite completion
• commit_comment - Comments on commits
• create - Branch or tag creation
• custom_property - Custom property changes for team assignments
• custom_property_values - Custom property values changes
• delete - Branch or tag deletion
• deployment - Deployment activities
• deployment_review - Deployment review processes
• deployment_status - Deployment status updates
• fork - Repository fork events
• installation_target - GitHub App installation changes
• label - Label changes on issues and pull requests
• member - Member profile changes
• membership - Member additions and removals
• meta - GitHub App metadata changes
• milestone - Milestone changes
• organization - Organization-level changes
• public - Repository visibility changes
• pull_request - Pull request activities
• pull_request_review - Pull request review activities
• pull_request_review_comment - Review comment activities
• pull_request_review_thread - Pull request review thread activities
• push - Code pushes and commits
• release - Release publications and updates
• repository - Repository creation, deletion, and modifications
• star - Repository star events
• status - Commit status updates
• team - Team creation and modifications
• team_add - Team member additions
• watch - Repository watch events

Set up webhooks

Configure the Webhook URL and create a custom Event Secret for secure communication:

• Webhook URL: Use the following format based on your collector service deployment:

  • For HTTP: http://your-domain-name/github/sync/webhook
  • For HTTPS: https://your-domain-name/github/sync/webhook

  Example: If your collector service is deployed at collector.yourcompany.com, the webhook URL would be: https://collector.yourcompany.com/github/sync/webhook

• Event Secret: Generate a secure random string (32+ characters) for webhook authentication. Save this value as you'll need it for the GITHUB_APP_WEBHOOK_SECRET environment variable.

Generate and convert keys

1. After creating the GitHub App, you need to generate a private key. In your GitHub App settings, click Generate a private key. The app will automatically generate and download a unique App ID and a Private Key file (.pem format). Save these securely as they will be needed for the collector service configuration.

2. Convert your downloaded private key file to DER format and then encode it in Base64:

   Step 1: Convert .pem to DER format

   bash

   Copy

   $
   openssl rsa -outform der -in private-key.pem -out output.der

   Step 2: Encode the DER file in Base64

   bash

   Copy

   $
   # For Linux/macOS
   $
   base64 -i output.der -o outputBase64
   $
   cat outputBase64  # Copy this output
   $
   
   $
   # For Windows (using PowerShell)
   $
   [Convert]::ToBase64String([IO.File]::ReadAllBytes("output.der"))
   $
   
   $
   # Alternative for Windows (using certutil)
   $
   certutil -encode output.der temp.b64 && findstr /v /c:- temp.b64

   Copy the resulting Base64 string and use it as the value for GITHUB_APP_PRIVATE_KEY environment variable in your collector configuration.

✓ Success indicators:

• Github app is created successfully
• App ID and private key are securely saved
• Webhook URL is configured and accessible

Prepare environment variables

Before deploying the collector service, gather the following information:

Required environment variables

Optional SSL environment variables

The following are optional environment variables for making API HTTPS.

SSL certificate setup instructions

To obtain an SSL certificate from a trusted Certificate Authority (CA) for HTTPS configuration, follow these steps:

1. Generate a private key and a Certificate Signing Request (CSR):

   bash

   Copy

   $
   openssl req -new -newkey rsa:2048 -nodes -keyout mycert.key -out mycert.csr

2. Submit the CSR to your chosen CA: Submit the mycert.csr file to your chosen Certificate Authority (e.g., DigiCert, Let's Encrypt, GoDaddy).

3. Complete domain validation: Complete any required domain validation steps as instructed by the CA.

4. Download the certificate: Download the issued certificate files from the CA (commonly a .crt or .pem file).

5. Create a PKCS12 keystore: Combine the certificate and private key into a PKCS12 keystore:

   bash

   Copy

   $
   openssl pkcs12 -export -in mycert.crt -inkey mycert.key -out keystore.p12 -name mycert

6. Use the keystore: Use the generated keystore.p12 file as the value for SERVER_SSL_KEY_STORE in your Docker configuration.

Deploy the collector service

The collector service is delivered as a Docker image. Deployment can be done in one of two ways:

Option A: Using Docker Compose (recommended)

Create a Docker Compose file that automates the download and deployment of the service.

1. Create a docker-compose.yml file with the following content:

   version: '3.9'
   
   services:
     nr-ghe-collector:
       image: newrelic/nr-ghe-collector:tag # use latest tag available in dockerhub starting with v*
       container_name: nr-ghe-collector
       restart: unless-stopped
       ports:
         - "8080:8080"     # HTTP port, make 8443 in case of HTTPS
       environment:
         # Required environment variables
         - NR_API_KEY=${NR_API_KEY:-DEFAULT_VALUE}
         - NR_LICENSE_KEY=${NR_LICENSE_KEY:-DEFAULT_VALUE}
         - GHE_BASE_URL=${GHE_BASE_URL:-DEFAULT_VALUE}
         - GITHUB_APP_ID=${GITHUB_APP_ID:-DEFAULT_VALUE}
         - GITHUB_APP_PRIVATE_KEY=${GITHUB_APP_PRIVATE_KEY:-DEFAULT_VALUE}
         - GITHUB_APP_WEBHOOK_SECRET=${GITHUB_APP_WEBHOOK_SECRET:-DEFAULT_VALUE}
   
         # Optional SSL environment variables (uncomment and configure if using HTTPS)
         # - SERVER_SSL_KEY_STORE=${SERVER_SSL_KEY_STORE}
         # - SERVER_SSL_KEY_STORE_PASSWORD=${SERVER_SSL_KEY_STORE_PASSWORD}
         # - SERVER_SSL_KEY_STORE_TYPE=${SERVER_SSL_KEY_STORE_TYPE}
         # - SERVER_SSL_KEY_ALIAS=${SERVER_SSL_KEY_ALIAS}
         # - SERVER_PORT=8443
       #volumes: # Uncomment the line below if using SSL keystore
       #  - ./keystore.p12:/app/keystore.p12 # path to your keystore file
       network_mode: bridge
   
   networks:
     nr-network:
       driver: bridge

   Copy

2. Set your environment variables by replacing the DEFAULT_VALUE placeholders in the Docker Compose file with your actual values, or create environment variables on your system before running the command.

3. Run the following command to start the service:

   bash

   Copy

   $
   docker-compose up -d

Option B: Direct Docker image run

You can download the Docker image directly from our Docker Hub registry and run it using your organization's preferred CI/CD pipeline or deployment method. Note that the customer needs to pass all the environment variables listed above while starting the collector service.

✓ Success indicators:

• Collector service is running and accessible on the configured port
• Docker container logs show successful startup without errors
• Service responds to health checks (if configured)

Install the GitHub App on organizations

After the collector service is running, you need to install the GitHub App on the specific organizations you want to integrate:

1. Navigate to your GitHub Enterprise instance.
2. Go to Settings → Developer Settings → GitHub Apps.
3. Find the GitHub App you created in step 1 and click on it.
4. In the left sidebar, click Install App.
5. Select the organizations where you want to install the app.
6. Choose whether to install on all repositories or select specific repositories.
7. Click Install to complete the installation.

✓ Success indicators:

• Webhook deliveries appear in the GitHub App settings
• No authentication errors in the collector service logs

Complete integration setup in New Relic UI

Once the collector service is running and the GitHub App is installed on your GHE organization(s), complete the integration setup as instructed in the New Relic UI:

1. The corresponding GHE organizations will appear in the New Relic UI.

2. To start the initial data synchronization, click First time sync.

3. (Optional) Click On-demand sync to manually sync the data.

   tip

   You can manually synchronize the data once every 4 hours. The On-demand sync button remains disabled if sync has occurred within the previous 4 hours.

4. After you view the Sync started message, click Continue. The GitHub Enterprise Integration screen displays the count of teams and repositories, refreshing every 5 seconds. Allow 15-30 minutes for the complete import of all data (timing depends on repository count).

   

Viewing your data

On the GitHub Enterprise integration screen:

• To view the imported teams information on Teams, click Go to Teams.
• To view the imported repositories information on Catalogs, click Go to Repositories.

Configure team assignments (optional)

You can auto-assign GitHub repositories to their teams by adding teamOwningRepo as a custom property in GitHub Enterprise.

1. Create the custom property at the organization level and assign a value for the custom property at the repository level. Additionally, you can set up a custom property for multiple repositories at the organization level simultaneously.
2. Then, in New Relic Teams, enable the Automated Ownership feature, making sure to use team as the tag key.

Once this is set up, New Relic automatically matches each repo with its correct team.

For more information on creating custom properties, refer to the GitHub documentation.