---
title: "GitHub Action"
description: "Drop the ophi-dev/mehen action into a workflow to publish per-PR metric trends."
keywords: ["github action", "ci", "pull request", "metrics"]
---

The official **`ophi-dev/mehen`** GitHub Action computes changed-file metric trends on every pull
request, compares them against the base branch, and publishes a sticky comment with the deltas. It is
the primary consumption surface for mehen today.

<Frame caption="The sticky PR comment: a Source Code Metrics table with per-file this-PR-vs-main deltas, followed by a Documentation Metrics table for changed Markdown.">
  <img src="/images/pr-comment-metrics.png" alt="mehen GitHub Action sticky comment showing a Source Code Metrics table (Cyclomatic, Cognitive, Functions, LLOC, MI columns with green/red/white delta indicators) and a Documentation Metrics table (DMI, Words, FKGL, Link Debt, Filler Risk)." />
</Frame>

Each cell shows the new value with the base-branch value in parentheses and a colored indicator —
🟢 improvement, 🔴 regression, ⚪ no material change — so reviewers see at a glance which files a PR
made more or less complex.

## Minimal workflow

```yaml .github/workflows/mehen.yml
name: mehen
on: pull_request

jobs:
  mehen:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      pull-requests: write
      issues: write
    steps:
      - uses: actions/checkout@v6
        with:
          fetch-depth: 0

      - uses: ophi-dev/mehen@v1
        with:
          paths: src
```

That's the whole setup. The action installs the `mehen` CLI, runs `mehen diff` against the PR's base
branch, and posts a sticky comment with the per-file metric deltas.

## Polyglot monorepo

For monorepos, pass each tracked root and let mehen pick supported languages from changed files in those
trees:

```yaml
- uses: ophi-dev/mehen@v1
  with:
    paths: |
      crates/api/src
      apps/web/src
      tools
    thresholds: |
      cyclomatic=5
      cognitive=4
      loc.lloc=120
```

## Inputs

| Input | Default | Description |
|---|---|---|
| `version` | `""` (latest) | Version of the mehen npm package to run. |
| `install-method` | `npm` | How to provide the mehen CLI: `npm`, `cargo`, or `path`. |
| `mehen-path` | `mehen` | Path to a mehen executable when `install-method: path`. |
| `node-version` | `24` | Node.js version used by the action runner. |
| `paths` | `.` | Repository-relative files or directories to compare. Newline, comma, or semicolon separated. |
| `include` | `""` | Glob patterns to include. |
| `exclude` | `""` | Glob patterns to exclude. |
| `exclude-tests` | `true` | Exclude common test-file patterns (`*_test.go`, `**/__tests__/**`, `*.spec.ts`) on top of any user-provided excludes. |
| `metrics` | `""` | Comma-separated metrics passed to `mehen diff`. |
| `from` | `""` | Base git revision. Defaults to the PR base branch or `main`. |
| `to` | `""` | Head git revision. Defaults to the PR head SHA or `HEAD`. |
| `show-unchanged` | `false` | Include files where all selected metrics are unchanged. |
| `comment` | `true` | Create or update a pull request comment. |
| `github-token` | (workflow token) | GitHub token used to update PR comments. |
| `thresholds` | `""` | Adverse per-file delta limits, e.g. `cyclomatic=5,cognitive=3,loc.lloc=100`. |
| `fail-on-threshold` | `true` | Fail the action when any configured threshold is exceeded. |
| `comment-title` | `## 📊 Source Code Metrics` | Markdown heading used for the sticky comment. |

## Outputs

| Output | Description |
|---|---|
| `violations` | Number of threshold violations. |
| `report_json` | Path to the JSON diff report produced by mehen. |
| `report_markdown` | Path to the rendered Markdown report. |

## Permissions

The action needs to write PR comments:

```yaml
permissions:
  contents: read
  pull-requests: write
  issues: write
```

`contents: read` lets the runner check out the repo. `pull-requests: write` and `issues: write` let the
action upsert the sticky comment.

## Sticky comment

The action posts a single comment on the PR and updates it on each push instead of stacking new
comments. The Markdown layout, cell format, and callout catalog are documented on the
[PR comment design](/guides/pr-comment-design) page.

## Markdown documentation section

When a PR touches Markdown files, `mehen diff` emits a **Documentation Metrics** section inside the
same sticky comment, anchored by `<!-- mehen-docs -->` (visible in the screenshot above). It carries a
five-column headline table (DMI, Words, FKGL/Tateishi RS, Link Debt, Filler Risk), severity-ranked
callouts drawn from a fixed template catalog, and a collapsed drill-down with the deeper structural,
wording, and readability tables. On code-only PRs the section is suppressed entirely. The full
specification — anchor rules, cell format, callout catalog, and `--fail-on` gating — is on the
[PR comment design](/guides/pr-comment-design) page.

## SQL in the diff

SQL files are analyzed automatically and appear in the same **Source Code Metrics** table on the PR
comment. Because SQL and source-code files publish different metric families, a mixed PR renders a
single table whose columns are the union of each language's defaults — every row fills only the
columns its analyzer emits, and the rest render as `–`. This keeps SQL changes visible on the default
action path instead of silently dropping out. See [`mehen diff`](/commands/diff) for how the default
metric set is resolved per file language.

## Examples

<Tabs>
  <Tab title="Strict gating">
    ```yaml
    - uses: ophi-dev/mehen@v1
      with:
        paths: src
        thresholds: |
          cyclomatic=3
          cognitive=3
        fail-on-threshold: true
    ```
  </Tab>
  <Tab title="Comment-only (advisory)">
    ```yaml
    - uses: ophi-dev/mehen@v1
      with:
        paths: src
        fail-on-threshold: false
    ```
  </Tab>
  <Tab title="Pin a version">
    ```yaml
    - uses: ophi-dev/mehen@v1
      with:
        paths: src
        version: "1.1.0"
    ```
  </Tab>
  <Tab title="Use a pre-installed binary">
    ```yaml
    - run: cargo binstall --git https://github.com/ophi-dev/mehen mehen
    - uses: ophi-dev/mehen@v1
      with:
        install-method: path
        mehen-path: $(which mehen)
        paths: src
    ```
  </Tab>
</Tabs>

## See also

- [Commands → diff](/commands/diff) — the underlying CLI command.
- [Concepts → Thresholds and diffs](/concepts/thresholds-and-diffs).
- [PR comment design](/guides/pr-comment-design) — full Markdown spec.
