Use cases

1 · Review every merge request

Use it when you want every merge request reviewed by an AI that has read the whole repository, with comments on the exact lines and one summary note that updates in place.

Pipeline

# .gitlab-ci.yml of the project you want reviewed
include:
  - project: platform/mrsentry                 # your copy of mrsentry
    ref: v0.1.1
    file: templates/ci/mrsentry.gitlab-ci.yml

variables:
  MRSENTRY_IMAGE: registry.example.com/platform/mrsentry:slim   # review needs only slim

# what the template adds (simplified):
# mrsentry:review:
#   rules:  merge request pipelines only
#   script: mrsentry run mr
#   artifacts: mrsentry-out/ (report, code quality, dotenv)

Command

mrsentry run mr                                      # in CI: project, MR and token come from CI variables
mrsentry review --mr-url https://gitlab.example.com/group/app/-/merge_requests/42 --dry-run
                                                     # from a laptop: review one MR, post nothing

Re-runs never duplicate comments. Threads whose problem is fixed are resolved, and only files that changed since the last run are reviewed again.

2 · Block merges on serious findings

Use it when a high or critical finding should stop the merge, not just leave a comment.

Pipeline

include:
  - project: platform/mrsentry
    ref: v0.1.1
    file: templates/ci/mrsentry.gitlab-ci.yml

variables:
  MRSENTRY_OUTPUT__FAIL_ON: high               # exit 1 at high or critical (findings and image CVEs)

mrsentry:review:
  allow_failure:                               # the template allows every failure; narrow it
    exit_codes: [2, 6]                         # MR head moved, LLM outage: don't block on those

Then turn on Settings › Merge requests › Pipelines must succeed. Exit codes are listed in Troubleshooting.

Command

mrsentry run mr --fail-on high
mrsentry review --mr-url https://gitlab.example.com/group/app/-/merge_requests/42 --dry-run --fail-on high; echo $?

3 · Review before you push

Use it when developers want feedback in the terminal before they open a merge request. Only LLM credentials are needed; no GitLab token.

Setup

No pipeline: this runs on the developer's machine. Install the standalone binary, export one LLM key, then:

mrsentry review --local                      # commits, uncommitted edits and new files vs origin/main
mrsentry review --local --staged             # only what you're about to commit
mrsentry review --local --format json        # for editors and scripts (also: markdown)
mrsentry hook install                        # pre-push hook, blocks on high or worse
mrsentry hook install --type pre-commit --fail-on critical
git push --no-verify                         # skip the hook once

The hook blocks only when findings reach --fail-on. If the review itself can't run, for example when you're offline, it prints why and lets the push through.

4 · Fix image CVEs inside the merge request

Use it when the service ships as an Amazon ECR image, and each merge request should show its High/Critical CVEs and get the dependency upgrade pushed into its branch.

Pipeline

include:
  - project: platform/mrsentry
    ref: v0.1.1
    file: templates/ci/mrsentry.gitlab-ci.yml

variables:
  MRSENTRY_IMAGE: registry.example.com/platform/mrsentry:full          # fixes need build toolchains
  MRSENTRY_ECR_IMAGE: 123456789012.dkr.ecr.eu-west-1.amazonaws.com/orders-service
  MRSENTRY_AWS_ROLE_ARN: arn:aws:iam::123456789012:role/mrsentry-ci     # GitLab OIDC → AWS, no stored keys
  MRSENTRY_FIX_WHEN: manual                                            # someone clicks first (default: on_success)

# what the template runs (simplified):
# mrsentry:review → mrsentry run mr --image $MRSENTRY_ECR_IMAGE      writes mrsentry-out/fix-pipeline.yml
# mrsentry:fix    → trigger: include: artifact fix-pipeline.yml     runs mrsentry fix --mode existing-mr

Commands

mrsentry run mr --image 123456789012.dkr.ecr.eu-west-1.amazonaws.com/orders-service
mrsentry fix --mode existing-mr --scan-report mrsentry-out/mrsentry-report.json   # what the child job runs
mrsentry fix --image orders-service --mode existing-mr --mr-url https://gitlab.example.com/group/app/-/merge_requests/42 --dry-run

The fix prefers bumping the direct parent dependency, and falls back to pinning the transitive one. It is verified with your build command, and the bot's own commit doesn't trigger another fix. If the MR comes from a fork, which the bot can't push to, mrsentry posts the patch as a comment for the author instead.

5 · Nightly fix merge request

Use it when CVEs published after a release should still get fixed on the default branch, even when nobody opens a merge request.

Pipeline

include:
  - project: platform/mrsentry
    ref: v0.1.1
    file: templates/ci/mrsentry.gitlab-ci.yml

variables:
  MRSENTRY_IMAGE: registry.example.com/platform/mrsentry:full
  MRSENTRY_ECR_IMAGE: 123456789012.dkr.ecr.eu-west-1.amazonaws.com/orders-service
  MRSENTRY_AWS_ROLE_ARN: arn:aws:iam::123456789012:role/mrsentry-ci

# then: Build › Pipeline schedules › New schedule, e.g. "0 3 * * *" on main.
# The template's mrsentry:scheduled-fix job runs only in scheduled pipelines:
#   script: mrsentry run scheduled --image "$MRSENTRY_ECR_IMAGE"

Command

mrsentry run scheduled --image 123456789012.dkr.ecr.eu-west-1.amazonaws.com/orders-service
mrsentry run scheduled --image orders-service --dry-run       # show the plan, open nothing

A later run with the same CVEs updates the existing fix MR instead of opening another. When the CVEs change, the new fix MR replaces the old one, which is closed with a link to it.

6 · Report CVEs without changing code

Use it when you want the CVE picture for an image, such as for an audit or a release check: how ECR scans it, whether the results are fresh, and which dependency brings in each CVE. No commits, no MRs.

Pipeline

include:
  - project: platform/mrsentry
    ref: v0.1.1
    file: templates/ci/mrsentry.gitlab-ci.yml

variables:
  MRSENTRY_ECR_IMAGE: 123456789012.dkr.ecr.eu-west-1.amazonaws.com/orders-service
  MRSENTRY_AWS_ROLE_ARN: arn:aws:iam::123456789012:role/mrsentry-ci
  MRSENTRY_SCHEDULED_FIX: "false"              # reporting only: no nightly fix MR
  MRSENTRY_DISABLE_REVIEW: "true"              # and no MR review or MR fix, unless you also want use case 1

mrsentry:cve-report:
  extends: .mrsentry:base                      # image, AWS OIDC and artifacts from the template
  rules:
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
  script:
    - mrsentry ecr status --image "$MRSENTRY_ECR_IMAGE"
    - mrsentry scan --image "$MRSENTRY_ECR_IMAGE" --fail-on critical

Commands

mrsentry ecr status --image orders-service           # scan type, frequency, last scan, freshness verdict
mrsentry scan --image orders-service:1.4.2 --repo-path . --on-stale local --fail-on critical

7 · Make sure reviewer comments are addressed

Use it when you want to know, before merging, whether each open comment from a person has actually been dealt with in the code.

Pipeline

# a) as part of the review: report them in the overview note
variables:
  MRSENTRY_REVIEW__HUMAN_THREADS: report       # or fail: also exit 1

# b) or as its own gate job, which you can re-run after replying
mrsentry:threads:
  extends: .mrsentry:base
  rules:
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
  script:
    - mrsentry threads                          # prints each thread's status; posts nothing
  allow_failure: false

Command

mrsentry threads                                       # in CI
mrsentry threads --mr-url https://gitlab.example.com/group/app/-/merge_requests/42

mrsentry never resolves people's threads; it only reports on them. Its own threads are handled separately: it resolves them when the finding is fixed, and replies when someone answers (review.replies).

8 · Check the change against its ticket

Use it when merge requests implement GitLab issues or Jira tickets, and the review should say where the change misses or contradicts what was asked.

Pipeline

variables:
  JIRA_URL: https://jira.example.com
  MRSENTRY_ISSUES__JIRA_PROJECTS: '["PROJ","OPS"]'     # only look up these keys (lists are JSON)
# masked CI/CD variables:
#   JIRA_API_TOKEN    Jira Server/DC: a personal access token
#   JIRA_USER         Jira Cloud only: the account email, used with an API token

GitLab issues need nothing extra. They are on by default and use the same token as the review.

Command

mrsentry run mr          # linked issues are part of every review

9 · Enforce your team's rules

Use it when your team has security rules or conventions the reviewer should apply and cite, some of them simple enough to catch with a regular expression.

Pipeline

# .mrsentry/guidelines.yml in the reviewed repository
- id: ACME-SQL-01
  title: Use the query builder for dynamic SQL
  severity: high
  category: security
  files: ["src/**/*.py"]
  description: Raw SQL strings with interpolation are forbidden; use db.query().where(...).
  bad: cur.execute(f"SELECT * FROM t WHERE id = {id}")
  good: db.query(T).where(T.id == id)

# .gitlab-ci.yml: test the rules whenever they change
mrsentry:guidelines:
  image: registry.example.com/platform/mrsentry:slim
  rules:
    - changes: [.mrsentry/guidelines.yml]
  script:
    - mrsentry guidelines test                 # each pattern matches its bad example, not its good one

Command

mrsentry guidelines test --repo-dir .

10 · Alert Slack or Teams

Use it when the security or on-call team should hear about a critical finding or CVE as soon as it appears, without watching merge requests.

Pipeline

# masked CI/CD variable (on the project or its group):
#   MRSENTRY_NOTIFY_WEBHOOK   https://hooks.slack.com/services/…   or a Teams Workflows URL
variables:
  MRSENTRY_NOTIFY__MIN_SEVERITY: high          # default: critical

Command

mrsentry run mr          # and mrsentry run scheduled: alerts go out when the webhook is set

Messages carry titles, file locations and CVE ids, never code or secret values. Each item is sent once; what was already sent is remembered in the overview note.