Mergify Enterprise

The installation process is separated into several steps:

1. First create a Mergify application on your GHES installation
2. Install the application in an organization
3. Build the Mergify environment file
4. Start Mergify

GitHub App Creation

1. In the Settings page of your organization, on bottom left of the side menu, select GitHub Apps in Developer settings:

2. Then click on New GitHub App:

3. Enter all the requirements informations for the Mergify Engine:

1. GitHub App name: Mergify
2. Homepage URL: https://mergify.com
3. You must uncheck Expire user authorization tokens
4. Webhook URL: https://my-mergify.example.com/eventevent the URL where the Mergify engine is exposed suffixed by /event
5. Callback URL: https://my-mergify.example.com/auth/callback the URL where the Mergify engine is exposed suffixed by /auth/callback
6. Webhook secret: a random key shared between GitHub Enterprise and Mergify Engine.
😶
You can generate a secret with: ruby -rsecurerandom -e 'puts SecureRandom.hex(20)'
7. Check Enable SSL verification

8. The following repository permissions are required:
• Administration: Read-Only
• Checks: Read & Write
• Commit statuses: Read-only
• Contents: Read & Write
• Issues: Read & Write
• Metadata: Read-only
• Pages: Read & Write
• Pull requests: Read & Write
• Workflows: Read &Write
• Actions: Read-Only
9. The following organization permissions are required:
• Members: Read-only
10. The following account permissions are required:
• Email addresses: Read-only
11. The following events must be subscribed:
• Check run
• Check suite
• Issue comment
• Member
• Membership
• Pull request
• Pull request review
• Pull request review comment
• Push
• Repository
• Status
• Team
• Team add
12. You can find the purpose of these permissions here: https://docs.mergify.com/security/#github-app-required-permissions-19
4. Finish by clicking Create GitHub App:

5. Write down the App ID and Client ID:

6. On The bottom, click on Generate a new client secret and write down the generated client secret:

7. On The bottom, click on Generate a private key:

8. Save the generated file for later (we will encode it in base64 and be used as MERGIFYENGINE_PRIVATE_KEY).

Enroll an organization into the GitHub App

1. Click on Install App on the left side menu:

2. Then click Install on the organization you want Mergify automate your processes:

3. Select the repositories you need Mergify to be enabled and click Install:

Building the environment file

Mergify engine configuration file is contained in a file named mergify.env and is loaded by the engine at startup.

1. Create the file mergify.env with (at least) the following variables:
Copy

# The URLs of your GHES installation
MERGIFYENGINE_GITHUB_URL=https://myonpremise-ghe-installation.example.com

# The URL of the Mergify installation
MERGIFYENGINE_BASE_URL=https://my-mergify.example.com

# Mergify App configuration
MERGIFYENGINE_INTEGRATION_ID=<The App ID from the Mergify GitHub App setting page>
MERGIFYENGINE_PRIVATE_KEY=<The App private key encoded in base64>
MERGIFYENGINE_OAUTH_CLIENT_ID=<The App Client ID>
MERGIFYENGINE_OAUTH_CLIENT_SECRET=<The App client secret>
MERGIFYENGINE_WEBHOOK_SECRET=<The shared webhook secret>

MERGIFYENGINE_CACHE_TOKEN_SECRET=<A random secret>
MERGIFYENGINE_DATABASE_OAUTH_TOKEN_SECRET_CURRENT=<A random secret>

2. To set MERGIFYENGINE_PRIVATE_KEY value, encode the downloaded private key in base64 with the command below, and paste the result in the variable.
Copy

cat path/to/my/private/key/mergify.2021-05-26.private-key.pem | base64 -w0

3. To set MERGIFYENGINE_CACHE_TOKEN_SECRET and MERGIFYENGINE_DATABASE_OAUTH_TOKEN_SECRET_CURRENT values, generate two token secrets with:
Copy

ruby -rsecurerandom -e 'puts SecureRandom.hex(42)'

Mergify Engine Installation

1. Get the Docker image

Download the Docker image using docker pull.

$ cat mergify_registry_key.json | base64 | \
     docker login -u _json_key_base64 --password-stdin "https://registry.mergify.com"
$ docker pull registry.mergify.com/enterprise:8.2.0

2. Starting Mergify

Now that you have finished to setup GitHub and Redis, you can start Mergify in normal mode with a SUBSCRIPTION_TOKEN :

$ docker run \
      -d \
      -p 5000:5000 \
       --name mergify-engine \
      --env-file mergify.env \
      -e MERGIFYENGINE_SUBSCRIPTION_TOKEN=<mergify-subscription-token> \
      -e MERGIFYENGINE_STORAGE_URL=rediss://:password@my-redis:6363 \
      -e MERGIFYENGINE_DATABASE_URL=postgresql://postgres:password@postgres:5432/postgres \
     registry.mergify.com/enterprise:8.2.0

Or with a SUBSCRIPTION_LICENSE :

$ docker run \
      -d \
      -p 5000:5000 \
       --name mergify-engine \
      --env-file mergify.env \
      -e MERGIFYENGINE_SUBSCRIPTION_LICENSE=<mergify-subscription-license> \
      -e MERGIFYENGINE_STORAGE_URL=rediss://:password@my-redis:6363 \
      -e MERGIFYENGINE_DATABASE_URL=postgresql://postgres:password@postgres:5432/postgres \
     registry.mergify.com/enterprise:8.2.0

Check if everything has started correctly:

$ docker logs mergify-engine
14:37:06 system   | web.1 started (pid=10)
14:37:06 system   | worker.1 started (pid=11)

The engine is ready, and you can create your first .mergify.yml 🎉

Testing the dashboard

You can now log into the Mergify dashboard on https://my-mergify.example.com.

Testing the installation

To test the system:

1. Create and commit an empty .mergify.yml on the default branch of a repository where Mergify has been enabled.
2. Create a pull request on that repository.
3. You should get a new check run called Summary.

Now, you can automate your workflow by filling the .mergify.yml configuration file with your rules!

Table Of Contents

• GitHub App Creation
• Enroll an organization into the GitHub App
• Building the environment file
• Mergify Engine Installation
• 1. Get the Docker image
• 2. Starting Mergify
• Testing the dashboard
• Testing the installation