🛠️

Installation

Mergify Enterprise

🏠Architecture 🤝Requirements 🛠️Installation 🔧Manual Installation (Legacy)🚀Advanced Features 🦆Troubleshooting 🚧Maintenance 🗒️Release Notes

‣

Control Panel

Use the button below to add a new page. When it's ready to go live, drag it up into the synced block in the sidebar above.

🛠️Installation

Aether Tools

If you want to hide pages, you can move them into the toggle below ↓

‣

Hidden Pages

⚙️

This procedure can be used as a basis to build a more complex workflow using Kubernetes or Docker Compose.

Installing Mergify

The installation process is separated into two steps:

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.
Then restart the Mergify container with the downloaded configuration and the GitHub App Installer disabled.

🔼

Before installing Mergify, make sure to pick the latest available version. The example snippet in this doc relies on 7.6.1, but there might be a newer version.

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

🆚

You can see the available version on the releases page.

2. Start the installer mode

$ docker run --rm -d \
    --name mergify-engine \
    -p 5000:5000 \
    -e PORT=5000 \
    -e MERGIFYENGINE_INSTALLER=1 \
    mergifyio/engine:7.6.1

🔐

Security note: the installer can be safely exposed to the internet during this procedure. The installer is a static page that will post a form on the GitHub website. GitHub will then ask for confirmation about the creation of the resources. No data is stored on the server or the browser. The actual engine is not yet started.

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:

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

On the installer form, start by entering your GitHub server URL and 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

🔑

To start and use Mergify, you need a subscription token. If you do not have this token, reach out to your Mergify account manager or our support team.

💽

Make sure your Redis instance is ready and running at this stage.

‣

Optional: use Redis with TLS enabled

Redis server provides TLS termination, to be able to connect to such an instance you need to:

Use redis:// instead of rediss:// in the environment variable MERGIFYENGINE_STORAGE_URL

‣

Optional: use Redis with self-signed TLS certificate

Some Redis server providers set it up with self-signed certificates. In that case, to be able to connect to such an instance you need to:

Use redis:// instead of rediss:// in the environment variable MERGIFYENGINE_STORAGE_URL
Set MERGIFYENGINE_REDIS_SSL_VERIFY_MODE_CERT_NONE=1 in your environment variables.

Mergify will connect to Redis using encryption but will not verify the server certificate.

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

$ 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 \
     mergifyio/engine:7.6.1

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 🎉

❤️‍🩹

If you need to make sure Mergify works (healthcheck), you can use the Web server on http://container:5000/ and asserts that it returns an HTTP 307 code.

Testing the dashboard

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

Testing the installation

To test the system:

Create and commit an empty .mergify.yml on the default branch of a repository where Mergify has been enabled.
Create a pull request on that repository.
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