Mergify Enterprise

Installing Mergify

The installation process is separated into two steps:

1. First start the Mergify container without any configuration and the GitHub App Installer started to create your Mergify GitHub App on GitHub. This will generate a configuration file with the GitHub App credentials.
2. Then restart the Mergify container with the downloaded configuration and the GitHub App Installer disabled.

1. Get the Docker image

First, ensure you have the mergify_registry_key.json file to get access to Mergify docker images.

If you need help, ask your Mergify account representative or the Mergify customer support.

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. Start the installer mode

$ docker run --rm -d \
    --name mergify-engine \
    -p 5000:5000 \
    -e PORT=5000 \
    -e MERGIFYENGINE_INSTALLER=1 \
    registry.mergify.com/enterprise:8.2.0

3. Expose your container

At this stage, you need to make sure port 5000 of the Mergify container is exposed with a DNS entry and accessible through HTTPS on port 443 from your GHES installation.

In this documentation, we use https://mergify.mycompany.com as the external exposed address.

4. Verify the installer setup

Using your browser, connect to the installer HTTPS endpoint (e.g., https://mergify.mycompany.com) to ensure your reverse proxy works and provide the TLS termination.

If it works, you will see the first step of the installer:

5. Configure GitHub resources

The Mergify Installer runs two tasks on behalf of your GitHub organization:

1. Create a new GitHub App pointing the webhook URL to your HTTPS endpoint (https://mergify.mycompany.com in our example)
2. Install this newly created GitHub App on your Organization.

On the installer form, start by entering your organization login, and press Create:

You will be redirected to the GitHub website to confirm the creation of the GitHub App. Choose a name, such as mergify-my-organization, and click on Create GitHub App for <my-organization>:

You will be redirected back to the Mergify Installer:

Save the mergify.env configuration file and click on Install: you will be redirected to GitHub to confirm the installation of your GitHub App to your organization.

Click on Install again on the following screen:

The GitHub App creation and installation is finished. 🥳

6. Stop the Mergify GitHub App Installer

$ docker stop mergify-engine

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

• Installing Mergify
• 1. Get the Docker image
• 2. Start the installer mode
• 3. Expose your container
• 4. Verify the installer setup
• 5. Configure GitHub resources
• 6. Stop the Mergify GitHub App Installer
• Starting Mergify
• Testing the dashboard
• Testing the installation