Git integration for GitHub Enterprise Server

Overview

SnapLogic supports integrating with your on-premises GitHub Enterprise Server (GHES). You can use the app gateway, a secure transparent proxy, to route Git requests through your Groundplex, providing an additional layer of security for GHES. This support in the data plane helps your organization mitigate security risks and protect sensitive information.

To implement this solution, we are introducing a transparent proxy that the GitHub Enterprise Server (GHES) integration calls from the SnapLogic control plane to route through the proxy and reach the Git host servers through your Groundplex.

To enable interaction between GHES and SnapLogic,
  • A GHES administrator must create a GitHub App in GHES.
  • A network administrator must configure the network to allow communication between GHES and the SnapLogic control plane.
  • A SnapLogic Org admin (Environment admin) must configure the Org to integrate with GHES.

You need the following:

  • A GHES repository for SnapLogic assets
  • Other prerequisites for each step

Architecture

The App Gateway and OAuth flow form a comprehensive framework for secure, efficient, and controlled integration between external systems and GitHub Enterprise Server.

The App Gateway serves as a crucial intermediary, facilitating communication between your Groundplex and the Control Plane. It establishes two additional WebSocket connections to enable real-time data exchange and coordination between these components.

OAuth flow ensures secure authentication when accessing GHES resources. OAuth2 flow is a mechanism through which external applications or services authenticate themselves with GHES. It involves the exchange of authorization tokens, which are securely managed and validated by GHES. They enable external entities to interact with GHES resources based on the permissions granted through OAuth scopes.


OAuth2 flow when using GHES

Note: We recommend that you use this method to connect your Groundplex to the GHES machine. Previously, connectivity required IP filtering on requests to GHES from the SnapLogic control plane or endpoint restrictions, where a limited subset of API endpoints are available.

Workflow

Use the following workflow to integrate your on-premises GHES into your SnapLogic Org:


1: Create GitHubApp. 2: Configure your Org for Git. 3: Create the app gateway Git URL. 4: Connect the Groundplex to the app gateway.

Formulate the GHES URL

The app gateway requires that you create a GHES URL based on your Org. You add this URL to the Git On-Prem URL when you configure Git for your SnapLogic Org. The URL has the following format:

org-location-environment-appname.controlportname:port

Use the following segments to build in the GHES URL in the order that they are listed:

  • org: Org name
  • location: location of your groundplex. Always sidekick.
  • environment: the value in the Environment field in the Snaplex Settings tab.
  • appname: github
  • controlplanename: the value for the control plane your Org connects to:
    • Production: appgateway.prod.snaplogic.io:8095
    • UAT: appgateway.uat.snaplogic.io:8095
    • EMEA: appgateway.emea.snaplogic.io:8095

For a Groundplex having environment dev running GHES in the Org test on your control plane, the gateway URL would be as follows:

http://test-sidekick-dev-github.appgateway.prod.snaplogic.io:8095

Create GitHub App

Ensure that you have the following:
  • A subscription to the Git Integration for GHES.
  • GHES administrator permissions.
  1. Create and authorize the SnapLogic app as a GitHub App.
    1. Follow the GitHub instructions to create a new GitHub App.
      Register New GitHub App dialog

      Field Description / Recommended Setting
      GitHub App name The name of your GitHub App.

      Example: snaplogic-app
      Homepage URL The full URL to the GitHub app’s website. Users will install the app from this page.

      Example: https://your-GHES-server-URL/github-apps/snaplogic-app/
      Callback URL The full URL to redirect to after the installation is authorized.

      Example: https://elastic.snaplogic.com/api/1/rest/asset/app/oauthcallback
      Expire user authorization tokens Enable this option.
      Permissions > Repository administration
      • Contents: Read & write
      • Deployments: Read & write
      • Issues: Read & write
      • Pull Requests: Read & write
      Where can this GitHub App be installed Any Account
      Note: Save the general information about the App including the App ID, which will be required for SnapLogic configuration.
    2. Install the newly created GitHub App for the appropriate GHES organization.
    3. Use the buttons on the About page of the GitHub App to generate and save a client secret and a private key.

      The generated private keys are automatically downloaded in a .pem file.

  2. Configure the network with the following settings:
    Destination: SnapLogic Manager - Configure Git dialog Source: GHES GitHub App creation
    Client ID Available from the GitHub App.
    Client Secret Generated in the About page of the GitHub App.
    GHES URL Homepage URL
    App ID GitHub App name
    Private Key Generated in the About page of the GitHub App. The private key is stored in a .pem file that is automatically downloaded.

Configure SnapLogic Org

  1. In SnapLogic Manager, go to Settings > Git Integration > Configure Git.
  2. In the Configure Git dialog, set Git integration type as GitHub Enterprise Server, and fill in the settings.
    GHES configuration form.

    Field Description
    Client ID The value stored in the GitHub App.
    Client Secret The field displays this value until you save the configuration, then it is hidden. Afterwards, the only way to change it is to replace it.
    GHES URL The gateway URL used for the secure connection between your Groundplex and on-premises GHES machine.
    Auth URL The public Homepage URL used in the GitHub App creation.
    Note: This field now takes the Homepage URL, which formerly was used as the GHES URL.
    App ID The GitHub App installation ID
    Private Key Copy and paste the RSA key from the .pem file generated during the GitHub App creation.
  3. Click Save.
Individual users must authorize SnapLogic to access their Git provider account.

Configure your Groundplex for the App Gateway

Before you begin
  • Ensure that the Groundplex is in the same network as your GHES host.
  • Log into the Org configured for integration with the GHES.
  1. In Manager, click the target Snaplex to open the Settings dialog.
  2. Click the Node Properties tab.
    On-premises Git configuration on Snaplex Node Properties tab

  3. Under Global Properties, click to add the gateway key-value pair.
  4. Enter the information about the app gateway.
    • Key: jcc.app.gateway.github
    • Value: https://my_git_servername.example.com
  5. Click Update.