Quickstart
From sign-in to your first cost comment in about five minutes.
Automatic setup (recommended)
- Sign in with GitHub at mergecost-api.jdtensor.com. This starts your 30-day trial on one repository — no card required.
- Click Install the MergeCost GitHub App and choose the repository. GitHub returns you to the dashboard.
- Pick the repository and click Add & set up automatically. MergeCost:
- creates the
MERGECOST_API_KEYrepository secret, - detects your stack (framework, package manager, test runner, Python/Node version),
- opens a pull request with
.github/workflows/mergecost.yml,.mergecost.ymland, for Jest, a one-line config change.
- creates the
- 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. - 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.