GitHub Integration

By default, code for Dash apps deployed to Dash Enterprise is stored in Gitea, which runs within the Dash Enterprise namespace.

Administrators with access to the Dash Enterprise Helm chart can integrate Dash Enterprise with their GitHub organization. This must be done at the Dash Enterprise installation time (in the future, it may be possible to integrate GitHub after a complete Dash Enterprise installation). With GitHub integrated, the code for Dash apps lives in GitHub repositories belonging to the integrated organization instead of in Gitea.

Dash Enterprise does not support storing code in both Gitea and GitHub.

Support for other Git-based version control platforms may be added in the future.

Overview

When GitHub is integrated with Dash Enterprise, a webhook detects when code is pushed to GitHub and triggers and build and deploy of the app on Dash Enterprise. Actions that push code include local git commands, pull request merges, as well as deploys initiated from Dash Enterprise (such as one-click deploy in workspaces).

Dash Enterprise respects the rules for the GitHub repositories that code is stored in. For example, users with no write access to the repository cannot push code to it from Dash Enterprise.

Integrating GitHub with Dash Enterprise changes how developers initialize and deploy apps.

Prerequisites

• A GitHub organization in which you have the owner role. All app developers on Dash Enterprise must be members of the organization.
• Access to the Dash Enterprise Helm chart.
• kubectl access to the Kubernetes cluster where Dash Enterprise is installed.
• Permission to manage the Kubernetes cluster where Dash Enterprise is installed in an administrator capacity.

Integrating GitHub

Creating and Configuring the GitHub App

First, you’ll create a GitHub App in your GitHub organization that will handle the connection between Dash Enterprise and your GitHub organization.

To create and configure the GitHub App:

1. In your GitHub organization settings, go to Developer settings.
2. In GitHub Apps, select New GitHub App
3. Configure the GitHub App:
4. In GitHub App name, give the App a name. In the example below, we’ve called it Dash Enterprise integration.
5. Enter a description for the GitHub App.

6. In Homepage URL, enter your Dash Enterprise URL.

   <img>

7. Go to the Identifying and authorizing users section and configure the parameters as follows:

   1. In Callback URL, enter https://api-<your-domain>/v1/git-callback (substituting <your-domain> for your Dash Enterprise base domain).
   2. Make sure that Expire user authorization tokens is selected.
   3. Make sure that Request user authorization (OAuth) during installation is not selected.
   4. Make sure that Enable Device Flow is not selected.

   <img>

   5. Go to the Webhook section and configure the parameters as follows:
   6. Make sure that Active is selected.
   7. In Webhook URL, enter https://api-<your-domain>/v1/git-webhook (substituting <your-domain> for your Dash Enterprise base domain).

   8. In Secret, enter a secure string. (Store it for later).

      Tip: You can generate a random secure string with openssl rand -hex 32.

      <img>

   9. Go to the Permissions section and do the following:

   10. Expand Repository permissions.
   11. Set Administration to Read and write (required for creating repositories on behalf of Dash Enterprise users when they create apps from scratch or from the App Catalog).
   12. Set Contents to Read and write (required for repository content access and token creation).
   13. Set Metadata to Read-only (required for obtaining and validating repository information).
   14. Expand Organization permissions.

   15. Set Members to Read-only (required for obtaining and validating organization member information).

   16. Go to the Subscribe to events section and select Push (required for triggering app builds on Dash Enterprise).

   17. For Where can this GitHub App be installed?, make sure Only on this account is selected.

8. Select Create GitHub App. You are taken to the newly created App.

9. In the left sidebar, select Install App.
10. Next to the GitHub organization that you want to integrate with Dash Enterprise, select Install.
11. Choose whether to install the GitHub App for all repositories under the organization or only select repositories (specifying which ones).

<img>

8. Select Install.
9. Note the installation ID in the URL (https://github.com/settings/installations/<installation-id>). You’ll need it in a later step.

Generating Secrets for the GitHub App

To generate required secrets for the GitHub App:

1. Go to your GitHub App General settings.
2. Next to Client secrets, select Generate a new client secret. Copy and store it securely for later use.
3. Go to the Private keys section.
4. Select Generate a private key.
5. Download the .pem file and store it securely for later use.

Creating the GitHub App Kubernetes Secret for Dash Enterprise

Must be done after the Dash Enterprise namespace is created in the cluster.

In this step, you’ll create a Kubernetes secret in the cluster where Dash Enterprise is installed. This secret is namespace-scoped and contains sensitive information about the GitHub App.

To create the secret:

kubectl create secret generic github-app \
  --namespace=$NAMESPACE \
  --from-literal=GITHUB_WEBHOOK_SECRET="<github-app-webhook-secret>" \
  --from-literal=GITHUB_CLIENT_SECRET="<github-app-client-secret>" \
  --from-file=GITHUB_APP_PRIVATE_KEY="<github-app-private-key-path>"

where:

• <github-app-webhook-secret> is the webhook secret that you defined when configuring the GitHub App.
• <github-app-client-secret> is the GitHub App client secret that you generated in the previous step.
• <github-app-private-key-path> is the absolute or relative path to the GitHub App private key file that you downloaded in the previous step.

Verify with:

kubectl get secret github-app -n $NAMESPACE -o yaml

Creating the GitHub App ConfigMap for Dash Enterprise

Must be done after the Dash Enterprise namespace is created in the cluster.

In this step, you’ll create a ConfigMap in the cluster where Dash Enterprise is installed. This ConfigMap is namespace-scoped and contains non-sensitive information about the GitHub App.

To create the ConfigMap:

kubectl create configmap github-app \
  --namespace=$NAMESPACE \
  --from-literal=GITHUB_CLIENT_ID="<github-app-client-id>" \
  --from-literal=GITHUB_INSTALLATION_ID="<github-app-installation-id>"

where:

• <github-app-client-id> is the client ID displayed in the GitHub App settings.
• <github-app-installation-id> is the ID that you copied after installing the GitHub App.

Verify with:

kubectl get configmap github-app -n $NAMESPACE -o yaml

Enabling GitHub Integration

GitHub integration is disabled for Dash Enterprise by default. It needs to be enabled at installation time.

Note that with GitHub integration enabled, Gitea will still be installed unless --set gitea.enabled=false is set in the helm install command. It is safe to keep Gitea in the Dash Enterprise namespace, but administrators who prefer to minimize Dash Enterprise’s footprint in the cluster should disable it.

To enable GitHub integration at installation time:

1. Extract the values.yml file from the Helm chart if you haven’t already.
2. Create a copy of the values.yml file that you’ll use for overriding the default values (again, if you haven’t already). You can call it something like values-custom.yml.
3. In your custom values file, find the feature flag for GitHub integration and change the value to true:
   yml # -- Enable GitHub integration deGithubIntegrationEnabled: true

4. Find the following lines and make sure that the names for the Kubernetes secret and ConfigMap match what you created in the previous steps. If you used different names for the Kubernetes secret and ConfigMap, edit the names here.
   yml # GitHub app configuration githubApp: # -- Name of secret containing GITHUB_CLIENT_ID, GITHUB_INSTALLATION_ID existingSecret: "github-app" # -- Name of config containing GITHUB_APP_PRIVATE_KEY, GITHUB_CLIENT_SECRET existingConfigmap: "github-app"

5. Continue with your installation.

Known Limitations

• Integrating GitHub must be done at installation time. In the future, it may be possible to integrate GitHub after a complete Dash Enterprise installation.
• Monorepos (where each app lives in a subfolder of a single repository) are not supported.
• Deploying apps with de deploy is not supported (git commands are).
• When initializing an app from the App Catalog (“Use App Template”), any services required by the app (Redis or Postgres) are not automatically added. This means that the initial deploy will fail. Add the required service for subsequent deploys to succeed.
• When working in a workspace created from a commit, users need to first check out the app branch (git checkout <branch>) to use one-click deploy. Otherwise, one-click deploy fails with an error similar to
  sh error: src refspec detached does not match any error: src refspec from does not match any error: failed to push some refs to 'https://github.com/<github-org>/<repo>'