Mergify Enterprise
ArchitectureRequirementsInstallationManual Installation (Legacy)Advanced FeaturesTroubleshootingMaintenanceRelease NotesUse 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.
InstallationIf you want to hide pages, you can move them into the toggle below ↓
The installation process is separated into several steps:
- First create a Mergify application on your GHES installation
- Install the application in an organization
- Build the Mergify environment file
- Start Mergify
GitHub App Creation
- In the Settings page of your organization, on bottom left of the side menu, select GitHub Apps in Developer settings:
- Then click on New GitHub App:
- Enter all the requirements informations for the Mergify Engine:
- GitHub App name:
Mergify
- Homepage URL:
https://mergify.com
- You must uncheck
Expire user authorization tokens
- Webhook URL:
https://my-mergify.example.com/event
event the URL where the Mergify engine is exposed suffixed by/event
- Callback URL:
https://my-mergify.example.com/auth/callback
the URL where the Mergify engine is exposed suffixed by/auth/callback
- Webhook secret: a random key shared between GitHub Enterprise and Mergify Engine.
- Check
Enable SSL verification
- 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
- The following organization permissions are required:
- Members: Read-only
- The following account permissions are required:
- Email addresses: Read-only
- 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
- You can find the purpose of these permissions here: https://docs.mergify.com/security/#github-app-required-permissions-19
- Finish by clicking Create GitHub App:
- Write down the App ID and Client ID:
- On The bottom, click on Generate a new client secret and write down the generated client secret:
- On The bottom, click on Generate a private key:
ruby -rsecurerandom -e 'puts SecureRandom.hex(20)'
- 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
- Click on Install App on the left side menu:
- Then click Install on the organization you want Mergify automate your processes:
- 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.
- Create the file
mergify.env
with (at least) the following variables: - To set
MERGIFYENGINE_PRIVATE_KEY
value, encode the downloaded private key in base64 with the command below, and paste the result in the variable. - To set
MERGIFYENGINE_CACHE_TOKEN_SECRET
andMERGIFYENGINE_DATABASE_OAUTH_TOKEN_SECRET_CURRENT
values, generate two token secrets with:
# 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>
cat path/to/my/private/key/mergify.2021-05-26.private-key.pem | base64 -w0
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
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 ofrediss://
in the environment variableMERGIFYENGINE_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 ofrediss://
in the environment variableMERGIFYENGINE_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 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 🎉
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!