Deploying Mergeable

Introduction

Mergeable is a highly configurable GitHub bot that helps automate and enforce your pull request workflows. Running as a GitHub App, Mergeable can validate PR titles, descriptions, labels, and more, automatically merge PRs when conditions are met, and help maintain consistent contribution standards across your repositories.

Built with Node.js and designed for flexibility, Mergeable uses YAML configuration files stored in your repositories, making it easy to customize rules on a per-repository basis. Whether you need to enforce conventional commits, require certain labels, or auto-merge Dependabot updates, Mergeable can handle it.

Key highlights of Mergeable:

• Flexible Validation: Validate PR titles, descriptions, labels, reviewers, and more
• Auto-Merge: Automatically merge PRs when all conditions are satisfied
• Auto-Assignment: Assign reviewers and labels based on rules
• Branch Protection: Enforce branch naming conventions and requirements
• Issue Management: Validate and manage issues with similar rules
• Customizable Actions: Comment, approve, request changes, or add labels
• Per-Repository Config: Configure rules differently for each repository
• Recipe System: Use pre-built recipes for common workflows
• Status Checks: Report validation results as GitHub status checks
• Self-Hosted: Run your own instance for privacy and control

This guide walks through deploying Mergeable on Klutch.sh using Docker, configuring it as a GitHub App, and setting up workflow automation rules.

Why Deploy Mergeable on Klutch.sh

Deploying Mergeable on Klutch.sh provides several advantages for GitHub workflow automation:

Simplified Deployment: Klutch.sh automatically detects your Dockerfile and builds Mergeable without complex orchestration. Push to GitHub, and your bot deploys automatically.

HTTPS by Default: Klutch.sh provides automatic SSL certificates, which are required for GitHub App webhooks.

GitHub Integration: Connect your configuration repository directly from GitHub. Updates trigger automatic redeployments.

Scalable Resources: Allocate CPU and memory based on your webhook volume and processing needs.

Custom Domains: Assign a custom domain for your GitHub App webhook endpoint.

Always-On Availability: Your bot runs 24/7, processing webhooks immediately when PRs are created or updated.

Privacy: Self-hosting means your repository data and PR information stays under your control.

Prerequisites

Before deploying Mergeable on Klutch.sh, ensure you have:

• A Klutch.sh account
• A GitHub account with organization admin access
• Basic familiarity with Docker and containerization concepts
• A GitHub organization or personal account where you can create GitHub Apps
• (Optional) A custom domain for your webhook endpoint

Creating a GitHub App

Before deploying Mergeable, you need to create a GitHub App:

Register the App

1. Go to GitHub Settings > Developer settings > GitHub Apps
2. Click New GitHub App
3. Fill in the details:
   • Name: Your Mergeable instance name
   • Homepage URL: Your deployment URL (can update later)
   • Webhook URL: https://your-app.klutch.sh/webhook (update after deployment)
   • Webhook secret: Generate a secure random string
4. Set permissions:
   • Repository permissions:
     • Contents: Read & write
     • Issues: Read & write
     • Pull requests: Read & write
     • Checks: Read & write
     • Metadata: Read-only
   • Organization permissions:
     • Members: Read-only
5. Subscribe to events:
   • Pull request
   • Pull request review
   • Pull request review comment
   • Issues
   • Issue comment
   • Status
   • Check run
   • Check suite
6. Click Create GitHub App

Generate Private Key

1. After creating the app, scroll to Private keys
2. Click Generate a private key
3. Save the downloaded .pem file securely

Note the App ID

Copy the App ID from the app’s settings page.

Preparing Your Repository

To deploy Mergeable on Klutch.sh, create a GitHub repository containing your Dockerfile and configuration.

Repository Structure

mergeable-deploy/
├── Dockerfile
├── README.md
└── .dockerignore

Creating the Dockerfile

Create a Dockerfile in the root of your repository:

FROM node:18-alpine

# Set working directory
WORKDIR /app

# Clone Mergeable
RUN apk add --no-cache git \
    && git clone https://github.com/mergeability/mergeable.git . \
    && rm -rf .git

# Install dependencies
RUN npm install --production

# Create directory for private key
RUN mkdir -p /app/keys

# Set environment variables
ENV NODE_ENV=production
ENV PORT=3000

# Expose port
EXPOSE 3000

# Health check
HEALTHCHECK --interval=30s --timeout=10s --start-period=30s --retries=3 \
  CMD wget --no-verbose --tries=1 --spider http://localhost:3000/ || exit 1

# Start Mergeable
CMD ["npm", "start"]

Environment Variables Reference

Variable	Required	Default	Description
APP_ID	Yes	-	GitHub App ID
WEBHOOK_SECRET	Yes	-	GitHub webhook secret
PRIVATE_KEY	Yes	-	GitHub App private key (PEM content or base64 encoded)
GHE_HOST	No	-	GitHub Enterprise hostname (if applicable)
LOG_LEVEL	No	info	Logging level
PORT	No	3000	Application port

Deploying on Klutch.sh

Prepare Your Private Key

Base64 encode your private key for storage as an environment variable:

base64 -i your-private-key.pem

Push Your Repository to GitHub

Initialize your repository and push to GitHub:

git init
git add Dockerfile .dockerignore README.md
git commit -m "Initial Mergeable deployment configuration"
git remote add origin https://github.com/yourusername/mergeable-deploy.git
git push -u origin main

Create a New Project on Klutch.sh

Navigate to the Klutch.sh dashboard and create a new project. Give it a descriptive name like “mergeable” or “github-bot”.

Create a New App

Within your project, create a new app. Connect your GitHub account if you haven’t already, then select the repository containing your Mergeable Dockerfile.

Configure HTTP Traffic

Mergeable receives webhooks over HTTP. In the deployment settings:

• Select HTTP as the traffic type
• Set the internal port to 3000

Set Environment Variables

Add the following environment variables:

Variable	Value
APP_ID	Your GitHub App ID
WEBHOOK_SECRET	Your webhook secret
PRIVATE_KEY	Your base64-encoded private key
LOG_LEVEL	info

Deploy Your Application

Click Deploy to start the build process. Klutch.sh will:

• Detect your Dockerfile automatically
• Build the container image
• Start the Mergeable container
• Provision an HTTPS certificate

Update GitHub App Webhook URL

After deployment, update your GitHub App settings:

1. Go to your GitHub App settings
2. Update the Webhook URL to https://your-app.klutch.sh/webhook
3. Save changes

Install the App

1. Go to your GitHub App’s public page
2. Click Install
3. Select the repositories where you want Mergeable active

Configuring Mergeable

Repository Configuration

Create a .github/mergeable.yml file in each repository:

version: 2
mergeable:
  - when: pull_request.*
    validate:
      - do: title
        must_include:
          regex: '^\[(feat|fix|docs|style|refactor|test|chore)\]'
          message: 'Title must start with [feat], [fix], [docs], etc.'
      - do: description
        no_empty:
          enabled: true
          message: 'Please provide a description for your PR'
    pass:
      - do: checks
        status: 'success'
    fail:
      - do: checks
        status: 'failure'

Validation Rules

Common validation options:

# Validate PR title
- do: title
  must_include:
    regex: 'pattern'
  must_exclude:
    regex: 'WIP|Draft'

# Validate description
- do: description
  no_empty:
    enabled: true
  must_include:
    regex: '## Summary'

# Validate labels
- do: label
  must_include:
    regex: 'ready-for-review|bug|feature'
  must_exclude:
    regex: 'do-not-merge|blocked'

# Validate assignees
- do: assignee
  min:
    count: 1
  max:
    count: 3

Auto-Merge Configuration

Automatically merge PRs that pass validation:

version: 2
mergeable:
  - when: pull_request.*
    validate:
      - do: label
        must_include:
          regex: 'auto-merge'
      - do: approvals
        min:
          count: 2
      - do: status
        contexts:
          - 'ci/build'
          - 'ci/test'
        state: 'success'
    pass:
      - do: merge
        merge_method: squash

Auto-Assignment

Automatically assign reviewers:

version: 2
mergeable:
  - when: pull_request.opened
    validate: []
    pass:
      - do: assign
        assignees: ['team-lead']
      - do: request_review
        reviewers: ['reviewer1', 'reviewer2']

Common Recipes

Conventional Commits

Enforce conventional commit style:

version: 2
mergeable:
  - when: pull_request.*
    validate:
      - do: title
        must_include:
          regex: '^(feat|fix|docs|style|refactor|perf|test|build|ci|chore|revert)(\(.+\))?: .+'
          message: 'Title must follow Conventional Commits format'

Dependabot Auto-Merge

Auto-merge Dependabot PRs:

version: 2
mergeable:
  - when: pull_request.*
    validate:
      - do: author
        must_include:
          regex: 'dependabot\[bot\]'
      - do: status
        contexts:
          - 'ci/test'
        state: 'success'
    pass:
      - do: merge
        merge_method: squash

Work In Progress Detection

Block WIP PRs:

version: 2
mergeable:
  - when: pull_request.*
    validate:
      - do: title
        must_exclude:
          regex: 'WIP|\\[WIP\\]|Draft'
          message: 'Remove WIP from title when ready for review'
      - do: label
        must_exclude:
          regex: 'work-in-progress'

Troubleshooting

Webhooks Not Received

• Verify webhook URL in GitHub App settings
• Check webhook delivery logs in GitHub
• Confirm HTTPS certificate is valid
• Review Mergeable container logs

Validation Not Running

• Ensure .github/mergeable.yml exists
• Verify YAML syntax is correct
• Check that the app is installed on the repository
• Review configuration version number

Permission Errors

• Verify GitHub App permissions are correct
• Reinstall the app if permissions were changed
• Check that the private key is valid

Additional Resources

• Mergeable GitHub Repository
• Mergeable Documentation
• GitHub Apps Documentation
• Klutch.sh Deployments

Conclusion

Deploying Mergeable on Klutch.sh gives you a powerful, self-hosted GitHub bot that automates and enforces your pull request workflows. With flexible YAML-based configuration and support for complex validation rules, Mergeable helps maintain code quality and contribution standards across all your repositories.

The combination of Mergeable’s automation capabilities and Klutch.sh’s reliable infrastructure ensures your GitHub workflows run smoothly 24/7. Whether you’re enforcing conventional commits, auto-merging Dependabot updates, or ensuring PR descriptions meet standards, Mergeable on Klutch.sh provides the foundation for consistent, automated code review processes.