MergeCost

Quickstart

From sign-in to your first cost comment in about five minutes.

Automatic setup (recommended)

  1. Sign in with GitHub at mergecost-api.jdtensor.com. This starts your 30-day trial on one repository — no card required.
  2. Click Install the MergeCost GitHub App and choose the repository. GitHub returns you to the dashboard.
  3. Pick the repository and click Add & set up automatically. MergeCost:
    • creates the MERGECOST_API_KEY repository secret,
    • detects your stack (framework, package manager, test runner, Python/Node version),
    • opens a pull request with .github/workflows/mergecost.yml, .mergecost.yml and, for Jest, a one-line config change.
  4. Review the Before merging checklist in that PR — for example, copy the services: block (Postgres, Redis) from your existing CI if your tests need it — and merge.
  5. Open any pull request. The MergeCost job posts the cost comment within a few minutes.

The app asks for read/write access to contents, workflows, pull requests and Actions secrets, only on the repositories you select. It is used to open the setup PR and write the secret.

Add your traffic

Dollar figures depend on how often each endpoint is called. Fill in traffic in .mergecost.yml (requests per day per endpoint), or install the traffic SDK to measure it in production.

traffic:
  "GET /feed": 200000
  "POST /orders": 8000
endpoints:
  "GET /feed":
    collection_size: 50   # items per page in production
    list: true

All settings: configuration.

Optional: fail expensive PRs

Add fail_above: 500 and any PR that adds more than $500/month fails the check (the comment is still posted). Useful as a required status check.

Optional: production traffic SDK

Create an SDK key on the repository page in the dashboard, then:

# Django
pip install --index-url https://__token__:$MERGECOST_SDK_KEY@mergecost-api.jdtensor.com/simple/ \
  --extra-index-url https://pypi.org/simple/ mergecost-sdk

# settings.py
MIDDLEWARE = [..., "mergecost_sdk.django.MergeCostTrafficMiddleware"]
MERGECOST_SDK_KEY = os.environ["MERGECOST_SDK_KEY"]

The SDK sends only method, route template and request counts every five minutes. Measured traffic replaces .mergecost.yml numbers and raises confidence to high.

Manual setup

Prefer not to install the app? Create a CI key on the repository page, save it as the MERGECOST_API_KEY secret, and add this workflow:

name: MergeCost
on:
  pull_request:
    types: [opened, synchronize, reopened]
permissions:
  contents: read
  pull-requests: write
jobs:
  mergecost:
    if: github.event.pull_request.head.repo.full_name == github.repository
    runs-on: ubuntu-latest
    env:
      MERGECOST_API_KEY: ${{ secrets.MERGECOST_API_KEY }}
      MERGECOST_API_URL: https://mergecost-api.jdtensor.com
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - uses: actions/setup-python@v5
        with:
          python-version: "3.12"
      - run: pip install -r requirements.txt
      - run: |
          pip install --index-url "https://__token__:${MERGECOST_API_KEY}@mergecost-api.jdtensor.com/simple/" \
            --extra-index-url https://pypi.org/simple/ pytest-mergecost mergecost
      - run: >
          mergecost run --base "${{ github.event.pull_request.base.sha }}"
          --head "${{ github.event.pull_request.head.sha }}" --defer-exit
          --repo "${{ github.repository }}" --pr "${{ github.event.pull_request.number }}"
      - env:
          GITHUB_TOKEN: ${{ github.token }}
        run: >
          mergecost comment .mergecost/comment.md
          --repo "${{ github.repository }}" --pr "${{ github.event.pull_request.number }}"

For Node.js and Django manage.py test specifics, see supported stacks.