DocumentationAPI ReferenceTerraform ProviderStatus PageSchedule a DemoFree Trial
Documentation

GitHub Enterprise Integration

Suggest Edits

🚧

Note

GitHub Enterprise is only supported on env0 Organizations signed up for our Self-Hosted Agent.

Supported GitHub Enterprise Server versions are:

  • 2.21.13 and above
  • 3.x

Initial GitHub Enterprise Setup

For env0 to be able to clone your code and post back commit statuses when running Plan on Pull Request you need to create and install a personal env0 GitHub App on your organization.

This only needs to be done once per GitHub Server.

  1. Create GitHub App (Only Organization is currently supported)

    1. Name your GitHub app env0
    2. Set Homepage URL to https://env0.com
    3. Skip ahead to the Webhooks section
      • Make sure Active is checked
      • You will now need to set the Webhook URL and Secret.
      • To fetch these, go to the Templates page.
        • If a template does not exist, create a New Template
          • Choose IaC framework (e.g. Terraform/OpenTofu)
            • Add Name
            • Click Next
            • Click GitHub Enterprise.
            • Copy Webhook URL and Secret and set both on the GitHub App
        • If a template already exists, use the Existing Template and update it as necessary.
    4. Skip ahead to the Repository permissions section and grant the following permissions:
      • Checks - Read and write
      • Contents - Read-only
      • Deployments - Read and Write
      • Metadata - Read-only
      • Pull requests - Read and Write
    5. Skip ahead to the Subscribe to events section and check the following:
      • Push
      • Pull Request
    6. On "Where can this GitHub App be installed?" Check "Any account - Allow this GitHub App to be installed by any user or organization.". Note however - currently you may only install the app on a single organization of your choice on your GitHub Enterprise instance
    7. Click "Create GitHub App"
    8. Make a note of the App ID and Client ID
    9. Click the "Generate a new client secret" and make note of that secret. You'll need it later.
    10. Scroll all the way down and "Click the Generate a private key". A pem file will be downloaded and saved on your computer. You'll need it later.
    11. Under the "Display information", click the "Upload a logo..." button and upload a logo (Optional)

  2. On the lefthand side menu, click on Install App to install the app on the organization of your choice

    1. Note the env0 app may only be installed on a single organization at this time.
    2. Grant env0 access to all or selected repositories in the organization
    3. Once the installation is done completed - you'll need to make a note of the installation id. It is the last URL part of the page you are in: http://github-ee.acme.com/organizations/{my-organization}/settings/installations/{installation-id}

  3. You'll need the following set as Helm values when installing the env0 agent:

    • githubEnterpriseAppId - The App ID from step 1.8
    • githubEnterpriseAppClientId - The Client ID from step 1.8
    • githubEnterpriseAppInstallationId - The Installation ID from step 2.3
    • githubEnterpriseAppClientSecretEncoded - The App Client Secret from step 1.10 Please base64 encode it before setting it
    • githubEnterpriseAppPrivateKeyEncoded - The content of the pem file downloaded in step 1.9 Please base64 encode it before setting it

🚧

Note

If deploying via Docker, DO NOT base64 encode the following keys:

  • githubEnterpriseAppClientSecretEncoded
  • githubEnterpriseAppPrivateKeyEncoded

📘

Encode to Base64

You can open browser Dev Tools - go to console and use 

btoa("secret")

to encode the string to base 64

githubEnterpriseAppId: 111
githubEnterpriseAppClientId: xxxxxxx
githubEnterpriseAppInstallationId: 222
githubEnterpriseAppClientSecretEncoded: bb=
githubEnterpriseAppPrivateKeyEncoded: aa==
  1. Install the agent

Now you can create templates for GitHub Enterprise

New Template

  1. Click CREATE NEW TEMPLATE on the top right corner in the Templates screen.
  2. Pick your template type, enter a name for the template and then click NEXT
  3. Click the Github Enterprise button.
  4. Enter your repository's HTTPs URL. (e.g. https://github.acmecorp.com/env0/)
  5. If you would like to pull the code from a specific revision or branch, enter that in the Revision field. Leaving this field empty will use your default branch, which is usually “master”/"main".
  6. Specify the folder where your IaC files are located:
    1. For Terraform or OpenTofu files, use the Terraform Folder or OpenTofu Folder field as appropriate.
    2. If you're using another IaC framework, use the equivalent folder field provided.
    3. If your IaC files are at the root of the repository, leave this field empty.
  7. Click NEXT to proceed to the variables section
  8. Add environment and IaC variables that you'd like to be used during deployment, and then click on NEXT to go to the final "Projects" section
  9. Pick the projects that you'd like to have access to deploy this template, and then click on DONE to create the template.

Existing Template

If you would like to integrate an existing template with GitHub Enterprise:

  1. Go to the Templates screen, and click on Settings for the template you would like to integrate with GitHub Enterprise.
  2. Click on the VCS step. From there you can click on the GitHub Enterprise button, and integrate with GitHub Enterprise as you would for a new template.

Updated 16 days ago