ci: add changelog lint to catch malformed CHANGELOG.md

[tommasini]

Description

The automated main-version-bump PR for the 8.3.0 release cut never got created: MetaMask/github-tools's create-release-pr action crashed with Error: Malformed category header: '### **Before**' while regenerating CHANGELOG.md on the release-changelog/8.3.0 branch, because a prior PR's raw "Screenshots/Recordings" template text had been committed verbatim into the changelog instead of a clean entry. Nothing in mobile's CI validates CHANGELOG.md formatting today, so this kind of corruption is invisible until it silently breaks the release-cut pipeline.

This adds a changelog lint, mirroring the pattern metamask-extension already uses:

• scripts/lint-changelog.sh: a branch-aware wrapper around @metamask/auto-changelog validate (the same non-mutating parser the release pipeline's auto-changelog update uses internally, so it fails on the exact same malformed input). On release-oriented branches (release/X.Y.Z(-ota)?, release-changelog/X.Y.Z*) it adds --rc, which also verifies the current package.json version has a changelog section.
• lint:changelog / lint:changelog:rc scripts in package.json, wired into the existing scripts lint matrix in .github/workflows/ci.yml so it runs on every PR — including changelog PRs into release/* and release PRs into stable — without needing a new job.
• A one-time normalization of CHANGELOG.md via auto-changelog validate --fix, which stripped 718 extraneous blank lines (verified zero content lines added/removed) so the new check starts green instead of failing immediately on main.

Changelog

CHANGELOG entry: null

Related issues

Fixes:

Manual testing steps

Feature: Changelog validation in CI

  Scenario: CI catches a malformed changelog entry before it reaches the release pipeline
    Given a PR modifies CHANGELOG.md with an invalid category header (e.g. "### **Before**")

    When the `scripts` CI job runs `yarn lint:changelog`
    Then the job should fail with "Malformed category header"

  Scenario: CI validates release-branch changelogs in --rc mode
    Given a PR's head or base branch matches `release/X.Y.Z` or `release-changelog/X.Y.Z`

    When `yarn lint:changelog` runs
    Then it should invoke `auto-changelog validate --rc`
    And fail if the branch's current package.json version has no changelog section

  Scenario: main's CHANGELOG.md passes validation
    Given the CHANGELOG.md normalization included in this PR

    When `yarn lint:changelog` runs on `main`
    Then it should exit 0 with no errors

Locally verified: yarn lint:changelog passes on main; re-injecting the exact ### **Before** corruption that broke the 8.3.0 release cut reproduces the identical Malformed category header error; simulating release/8.3.0 / release-changelog/8.3.0 branch names via GITHUB_REF_NAME / GITHUB_HEAD_REF correctly switches the script into --rc mode.

Screenshots/Recordings

Before

N/A

After

N/A

Pre-merge author checklist

• I've followed MetaMask Contributor Docs and MetaMask Mobile Coding Standards.
• I've completed the PR template to the best of my ability
• I've included tests if applicable
• I've documented my code using JSDoc format if applicable
• I've applied the right labels on the PR (see labeling guidelines). Not required for external contributors.

Performance checks (if applicable)

• I've tested on Android
  • Ideally on a mid-range device; emulator is acceptable
• I've tested with a power user scenario
  • Use these power-user SRPs to import wallets with many accounts and tokens
• I've instrumented key operations with Sentry traces for production performance metrics
  • See trace() for usage and addToken for an example

For performance guidelines and tooling, see the Performance Guide.

Pre-merge reviewer checklist

• I've manually tested the PR (e.g. pull and build branch, run the app, test code being changed).
• I confirm that this PR addresses all acceptance criteria described in the ticket it closes and includes the necessary testing evidence such as recordings and or screenshots.

---

Note

Low Risk
Changes are limited to CI and changelog tooling; no runtime app behavior, with the main effect being failed PRs when CHANGELOG.md is invalid.

Overview
Adds CHANGELOG.md validation to the existing CI scripts matrix so every PR runs yarn lint:changelog, catching malformed changelog entries (e.g. invalid category headers) before they break release-cut automation.

Introduces scripts/lint-changelog.sh, which runs @metamask/auto-changelog validate --prettier and turns on --rc on release/*, release/*-ota, and release-changelog/* branches so the current package.json version must have a matching changelog section. package.json gains lint:changelog, lint:changelog:rc, and a repository field so auto-changelog can resolve the repo URL under Yarn Berry.

^{Reviewed by Cursor Bugbot for commit e081453. Bugbot is set up for automated code reviews on this repo. Configure here.}

[github-actions]

CLA Signature Action: All authors have signed the CLA. You may need to manually re-run the blocking PR check if it doesn't pass in a few minutes.

[metamask-ci]

PR template — items to address before "Ready for review"

Warnings — informational, address before merging:

• Related issues section is empty. Add Fixes: #123 / Closes: <URL> / Refs: <Jira key>, or write a short rationale after the colon.

See docs/readme/ready-for-review.md for the full Definition of Ready for Review.

[HowardBraham]

I have actually already been working on fixing all the problems with https://github.com/MetaMask/auto-changelog from that package, but this should help a little.

I put DO-NOT-MERGE on this for now, because I want to test it a little more.

[tommasini]

ah @HowardBraham sorry saw this now, almost merged it, will convert it to draft

[tommasini]

Converted to draft, until @HowardBraham thumbs up

[github-actions]

🔍 Smart E2E Test Selection

• Selected E2E tags: None (no tests recommended)
• Selected Performance tags: None (no tests recommended)
• Risk Level: low
• AI Confidence: 98%

click to see 🤖 AI reasoning details

E2E Test Selection:
All three changed files are purely CI/linting infrastructure changes with zero impact on app functionality or test flows:

1. .github/workflows/ci.yml: Adds lint:changelog to the list of CI scripts. This only affects the CI pipeline's linting step — no app code, no test infrastructure.

2. package.json: Adds a repository metadata field (used by auto-changelog to resolve the GitHub repo URL automatically) and two new npm scripts (lint:changelog and lint:changelog:rc). No dependency versions changed, no app code affected.

3. scripts/lint-changelog.sh (new file): A bash script that validates CHANGELOG.md using @metamask/auto-changelog. It's a pure CI utility with no impact on app behavior, test infrastructure, or user flows.

None of these changes touch app source code, UI components, controllers, navigation, test page objects, selectors, flows, or any other code that could affect E2E test outcomes. No E2E smoke tags are warranted.

Performance Test Selection:
No app code, performance-sensitive flows, or performance test specs were changed. The PR only adds changelog validation to CI and a repository metadata field to package.json. There is no plausible performance impact.

View GitHub Actions results

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, have a team admin enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit e081453. Configure here.}

[cursor]

RC lint ignores PR base branch

Medium Severity

lint-changelog.sh only treats GITHUB_HEAD_REF (then GITHUB_REF_NAME / current git branch) as release-oriented for --rc. Pull requests that target release/* or release-changelog/* with a non-matching head branch skip --rc, so CI may not verify that package.json’s version has a changelog section on those release PRs.

 

^{Reviewed by Cursor Bugbot for commit e081453. Configure here.}

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud