TL;DR: Added a markdownlint check to 33 repos at once — and woke up to ~100 CI failure emails about code I didn't write. The fix: lint only the files changed in the PR, never the whole backlog. Grandfather existing violations; enforce the standard on new changes.

I maintain a GitHub org with 33 open-source repos. Last month I decided to do the responsible thing: add a default markdownlint check to every repo so our docs stay consistent.

By the next morning I had ~100 failure emails in my inbox. Here's what went wrong — and the rollout playbook I'd use instead.

What happened

The lint workflow ran against every markdown file in each repo — READMEs, changelogs, and contributor guides written years ago by people who had never heard of markdownlint. Upstream markdown, as it turns out, has never passed a linter in its life. Trailing spaces, inconsistent heading levels, bare URLs — the works.

My inbox became a firehose of red X's on code I didn't write, in files I'd never touched, for rules nobody on those projects had agreed to.

The noise-vs-signal problem

This is the classic failure mode of adopting tooling across many repos at once:

  • Signal: "the file you just edited violates the style guide"
  • Noise: "a README from 2021 has trailing whitespace"

When 95% of failures are noise, people stop reading CI results entirely — and then the 5% that matter get ignored too. A check everyone ignores is worse than no check at all.

The fix: scope linting to the files you own

Instead of linting the whole repo, I changed the workflow to lint only files changed in the PR:

- uses: actions/checkout@v4 - name: Get changed files id: changed uses: tj-actions/changed-files@v44 with: files: | **/*.md - name: Lint changed markdown if: steps.changed.outputs.any_changed == 'true' run: npx markdownlint-cli ${{ steps.changed.outputs.all_changed_files }}

Overnight the emails stopped. CI went green on every repo, and the check still catches every new violation — which is the only thing it was ever supposed to do.

The broader lesson: a playbook for rolling out tooling across many repos

  1. Never lint the backlog on day one. Grandfather existing violations; enforce the standard on new changes only.
  2. Scope every check to what the PR touches. Changed-files linting, diff-aware tests, incremental type checks — same principle everywhere.
  3. Disable noisy upstream workflows you don't own rather than letting them train everyone to ignore red.
  4. Keep the checks you own green. A green build people trust beats a "thorough" build nobody reads.
  5. Roll out repo by repo if you can — 33 repos at once multiplies every mistake by 33.

Your CI should tell you about your code. The moment it starts yelling about code you didn't write, scope it down until the signal comes back.

Have you ever been buried by a noisy CI rollout? What did you do about it — scope it down, fix the backlog, or turn the check off? Tell me in the comments. 👇