Integrations

The command line writes plain files and returns clear exit codes, so it fits the tools you already use.

The building blocks

Every integration below uses the same three things from the command line:

The command: repolantern run <repository> --provider … --model … --cap …, with the key in an environment variable (a CI secret).
The exit code: 0 done, 1 stopped or failed, 2 wrong input, 3 paused, 130 stopped with Ctrl-C (details).
The report: owner_repo.report.json holds each guide's grounding score, the cost and the readiness checklist, so a script can read them with jq.

A quality gate in any CI

This script writes the guides and fails the build if any guide scores below a threshold:

#!/usr/bin/env bash
# Usage: OPENAI_API_KEY=... ./docs-gate.sh https://github.com/owner/repo [min_score]
set -uo pipefail
REPO="$1"; MIN="${2:-85}"
code=0
repolantern run "$REPO" --provider openai --model gpt-6-luna --skills beginner,senior --cap 1.00 --out docs/guide \
  || code=$?
[ "$code" -eq 0 ] || { echo "RepoLantern stopped with exit code $code"; exit "$code"; }
jq -r '.eval | to_entries[] | "\(.key): \(.value.score)/100"' docs/guide/*.report.json
jq -e --argjson min "$MIN" '[.eval[].score] | min >= $min' docs/guide/*.report.json > /dev/null \
  || { echo "a guide scored below $MIN"; exit 1; }

The grounding score measures how well a guide sticks to the code (names, paths, citations, sections), not whether every sentence is right (how we check).

GitHub Actions

A weekly guide for the repository the workflow runs in, kept as a build artifact. Add your key as the OPENAI_API_KEY repository secret:

name: Architecture guide
on:
  workflow_dispatch:
  schedule:
    - cron: "0 6 * * 1"   # every Monday 06:00 UTC
permissions:
  contents: read
jobs:
  guide:
    runs-on: ubuntu-latest
    timeout-minutes: 30
    steps:
      - uses: actions/setup-python@v5
        with:
          python-version: "3.12"
      - run: sudo apt-get update && sudo apt-get install -y graphviz libpango-1.0-0 libpangoft2-1.0-0
      - run: pipx install aelsha-repolantern
      - name: Write the guides
        env:
          OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
        run: >
          repolantern run "https://github.com/${{ github.repository }}"
          --provider openai --model gpt-6-luna --skills beginner,architect --cap 1.00 --out guide
      - name: Fail if a guide scores below 85
        run: jq -e '[.eval[].score] | min >= 85' guide/*.report.json
      - uses: actions/upload-artifact@v4
        with:
          name: repolantern-guide
          path: guide/

The command line reads public repositories, so this suits open-source projects.

GitLab CI

A scheduled pipeline job with Claude. Store ANTHROPIC_API_KEY as a masked CI/CD variable. RepoLantern needs git 2.50.1 or newer, so the job adds the official git PPA to Ubuntu:

repolantern_guide:
  image: ubuntu:24.04
  rules:
    - if: $CI_PIPELINE_SOURCE == "schedule"
  before_script:
    - apt-get update && apt-get install -y --no-install-recommends ca-certificates software-properties-common gpg-agent jq
    - add-apt-repository -y ppa:git-core/ppa
    - apt-get update && apt-get install -y --no-install-recommends git graphviz libpango-1.0-0 libpangoft2-1.0-0 pipx
    - pipx install aelsha-repolantern
    - export PATH="$HOME/.local/bin:$PATH"
  script:
    - repolantern run "$CI_PROJECT_URL" --provider anthropic --model claude-haiku-5-5 --cap 1.00 --out guide
    - jq -e '[.eval[].score] | min >= 85' guide/*.report.json
  artifacts:
    paths: [guide/]
    expire_in: 30 days

Docker

An image that runs as a non-root user, with a current git:

FROM ubuntu:24.04
RUN apt-get update && apt-get install -y --no-install-recommends ca-certificates software-properties-common gpg-agent \
 && add-apt-repository -y ppa:git-core/ppa \
 && apt-get update && apt-get install -y --no-install-recommends git graphviz libpango-1.0-0 libpangoft2-1.0-0 pipx \
 && rm -rf /var/lib/apt/lists/* \
 && PIPX_HOME=/opt/pipx PIPX_BIN_DIR=/usr/local/bin pipx install aelsha-repolantern
USER ubuntu
WORKDIR /work
ENTRYPOINT ["repolantern"]

docker build -t repolantern .
mkdir -p out
docker run --rm -e OPENAI_API_KEY -v "$PWD/out:/work/out" repolantern \
  run https://github.com/octocat/Hello-World --provider openai --model gpt-6-luna --cap 0.20

-e OPENAI_API_KEY passes the variable from your shell without writing the key on the command line. If your user id isn't 1000, add --user "$(id -u):$(id -g)" -e HOME=/tmp so the files in out/ are yours.

make

REPO ?= https://github.com/octocat/Hello-World
CAP  ?= 0.50

guide:  ## write the beginner and senior guides into ./guide
	repolantern run $(REPO) --provider openai --model gpt-6-luna --skills beginner,senior --cap $(CAP) --out guide
	jq -r '.eval | to_entries[] | "\(.key): \(.value.score)/100"' guide/*.report.json

Tell your team

One line for Slack, Microsoft Teams or e-mail, built from the report:

jq -r '"RepoLantern: " + ([.eval | to_entries[] | "\(.key) \(.value.score)/100"] | join(", "))
       + " · cost $" + (.totals.cost_usd | tostring) + " · \(.totals.calls) model calls"' out/owner_repo.report.json

For example: RepoLantern: beginner 97/100 · cost $0.05498 · 25 model calls. Send it with your chat tool's incoming webhook.

Publish the guides

The guides are plain Markdown with Mermaid diagrams, so they drop into most documentation tools:

MkDocs, Docusaurus or any static site generator: copy out/*.md into the docs folder in the same CI job. Mermaid renders with the generator's Mermaid plugin.
Backstage TechDocs: add the guides to the component's TechDocs docs/ folder and its mkdocs.yml navigation, so they appear beside its catalog entry.
Confluence, Notion or a wiki: import the Markdown, or post it through the tool's own API from CI.
A pull request: commit the refreshed guides to a branch so reviewers see what changed in the architecture.

The web app also exports a guide as PDF, Word, PowerPoint, HTML or draw.io (read and use your guide).

AI assistants

Guides made in the web app can be read and searched by an MCP or A2A assistant with a token you can revoke at any time: see Connect an AI assistant.