GitHub Enterprise

In addition to our out-of-the-box integration with GitHub, Spacelift also supports using GitHub Enterprise as the source of code for your stacks and modules. Only one GitHub Enterprise server can be used by a single Spacelift account.

Setting up the integration

In order to set up the integration from the Spacelift side, please navigate to the VCS Providers section of the admin Settings page and click the Set up button next to the GitHub Enterprise integration:

This should open a form like this one:

Create a GitHub App

Before you can complete this step you need to create a GitHub App in your GitHub Enterprise server. You will need the Webhook endpoint and Webhook secret while creating your App, so take a note of them.

You can either create the App in a user account or an organization account. Start by navigating to the GitHub Apps page in the Developer Settings for your account, and clicking on New GitHub App:

Give your app a name and homepage URL (these are only used for informational purposes within GitHub):

Enter your Webhook URL and secret:

Set the following Repository permissions:

Permission

Access

Checks

Read & write

Contents

Read-only

Deployments

Read & write

Metadata

Read-only

Pull requests

Read & write

Webhooks

Read & write

Commit statuses

Read & write

Set the following Organization permissions:

Permission

Access

Members

Read-only

Subscribe to the following events:

  • Organization

  • Pull request

  • Push

  • Repository

Finally, choose whether you want to allow the App to be installed on any account or only on the account it is being created in and click on Create GitHub App:

Once your App has been created, make a note of the App ID in the About section:

Now scroll down to the Private keys section of the page and click on Generate a private key:

This will download a file onto your machine containing the private key for your GitHub app. The file will be named <app-name>.<date>.private-key.pem, for example spacelift.2021-05-11.private-key.pem.

Now that your GitHub App has been created, go back to the integration configuration screen in Spacelift, and enter your API host URL (the URL to your GitHub Enterprise server), the App ID, and paste the contents of your private key file into the Private key box:

Click on the Save button to save your integration settings.

Installing your GitHub App

Now that you've created a GitHub App and configured it in Spacelift, the last step is to install your App in one or more accounts in your GitHub Enterprise server. To do this, go back to GitHub Enterprise, find your App in the GitHub Apps page in your account settings, and click on the Edit button next to it:

Go to the Install App section, and click on the Install button next to the account your want Spacelift to access:

Choose whether you want to allow Spacelift access to all the repositories in the account, or only certain ones:

Congrats, you've just linked your GitHub Enterprise account to Spacelift!

Using GitHub Enterprise with stacks and modules

If your Spacelift account is integrated with GitHub Enterprise, the stack or module creation and editing forms will show a dropdown from which you can choose the VCS provider to use. GitHub Enterprise will always come first, assuming that you've integrated it with Spacelift for a good reason:

The rest of the process is exactly the same as with creating a GitHub-backed stack or module, so we won't go into further details.

Unlinking the Integration

If you no-longer need the integration, you can remove it via the Unlink button on the VCS Providers page:

Please note that unlinking the integration in Spacelift will not remove the GitHub App or its permissions from the Enterprise Server. You will need to do that yourself.

Also note that if you unlink your integration and then decide to enable it again, you will need to uninstall your GitHub App from any accounts it has access to, and then follow the steps to install it again. This is because Spacelift stores information required to access your GitHub Enterprise accounts that is lost when the integration is unlinked.