citegate

citegate

Citation integrity as a CI gate. citegate verifies every entry in your BibTeX files against Crossref, OpenAlex, and DBLP, then fails your build when a reference is fabricated, wrong, or retracted.

LLM writing assistants fabricate plausible-looking references, and even careful humans cite papers that later get retracted. Existing checkers are interactive tools you have to remember to run. citegate is the piece that belongs in your repository instead: a GitHub Action, a pre-commit hook, and a weekly monitor that opens an issue the day a paper you cite is retracted.

  OK         he2016deep
  NOT FOUND  fabricated2023  (best title similarity 0.42)
             - no record with a similar title in Crossref, OpenAlex, or DBLP — possibly a fabricated reference
  RETRACTED  wakefield1998retracted
             - OpenAlex marks this work as retracted
             - Crossref/Retraction Watch records: retraction

citegate: checked 3 entries — 1 verified, 1 retracted, 1 not-found

What it checks

Verdict	Meaning
verified	The entry matches a real indexed work (title, year, authors agree).
not-found	No similar record exists in Crossref, OpenAlex, or DBLP. Likely fabricated.
retracted	The cited work is retracted or withdrawn, per OpenAlex and the Retraction Watch data in Crossref.
mismatch	A real work exists, but the year, title, or authors in your entry disagree with the index.
unverifiable	Websites, standards, and other entries without a DOI that scholarly indexes do not cover. Never fails the build.
error	A source API was unreachable.

Entries with a DOI are resolved directly and their metadata compared field by field. Entries without a DOI are matched by fuzzy bibliographic search in Crossref and OpenAlex, with DBLP as a fallback for works they miss; strong matches also get a suggestion with the DOI you should add.

Quick start

pip install citegate            # or: pipx install citegate
citegate paper/references.bib --mailto [email protected]

--mailto is optional but recommended: it identifies you to the Crossref and OpenAlex APIs and places you in Crossref’s polite pool. The exit code is non-zero when any not-found or retracted entry appears (configurable with --fail-on not-found,retracted,mismatch), so the same command works locally and in CI. Add --json report.json for machine-readable output, --cache to skip unchanged entries on repeated runs, and --workers N to tune lookup concurrency (default 4).

GitHub Action

name: References
on: [push, pull_request]
jobs:
  citegate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: chrisyangsong/citegate@main
        with:
          files: '**/*.bib'
          mailto: '[email protected]'

Failures show up as inline annotations and a job-summary table listing exactly which entries are suspect and why.

Retraction monitoring

A bibliography that verified cleanly last month can go bad without you touching it: about one in 500 published papers is eventually retracted, and citing one in a submission is an avoidable reviewer complaint. Copy examples/retraction-monitor.yml into .github/workflows/ and citegate re-verifies your references every Monday, opening an issue in your repository when a cited paper is retracted or stops resolving.

For higher-frequency monitoring, --only retractions (or only: 'retractions' in the Action) skips search and metadata comparison entirely and just asks the indexes whether each DOI entry has been retracted — two requests per entry, cheap enough to run daily.

pre-commit hook

# .pre-commit-config.yaml
repos:
  - repo: https://github.com/chrisyangsong/citegate
    rev: v0.3.0
    hooks:
      - id: citegate

Relation to other tools

Several good interactive checkers exist, including refchecker and hallucinator for auditing a finished paper or PDF, and browser tools like BibTeX Verifier. citegate covers the other half of the problem: it lives in the repository with your .bib files, runs automatically on every push, and keeps watching after you stop looking. If you want a one-off deep audit of a PDF, use those tools; if you want your references checked continuously, use citegate.

Design notes

• Sources: Crossref (REST API, polite pool), OpenAlex, and DBLP as a search fallback for works without a DOI. Retraction status remains the union of OpenAlex’s is_retracted flag and Crossref update records, which include the Retraction Watch database.
• Matching is deliberately conservative: @misc and other non-indexed entry types without DOIs are skipped rather than flagged, and a one-year slack is allowed on years (print vs online dates). False alarms are the fastest way to get a checker removed from CI.
• No LLMs are involved in verification; every verdict is traceable to an index record.

Roadmap

• DOCX/PDF reference-list extraction (currently BibTeX only)
• arXiv as an additional source

Issues and pull requests are welcome.

License

MIT © 2026 Yang Song. Not affiliated with Crossref, OpenAlex, DBLP, or Retraction Watch; please respect their API terms.