GitHub

GitHub

Staleless keeps your Markdown in your own repository. Connecting one is how a project gets its content.

Connecting

1. Install the GitHub App

   Install it on the organisation that owns the repository. The app asks for the minimum permissions it needs.

2. Choose the repository

   One repository per project.

3. Choose the branch

   Your default branch. A merge to it publishes.

4. Choose the folder

   The path inside the repository that holds nav.yaml and pages/. Usually docs. A monorepo can hold several projects’ content in different folders.

What the connection means

From then on the repository is the content store. There is no copy inside Staleless to keep in step, and there is no push command.

Action	What actually happens
A writer saves	A staged change, then a commit on a branch.
An agent calls docs_commit	A commit on a branch.
Somebody merges	The site rebuilds. That is the publish.
A developer pushes to a branch	The writer shows the change.

An app, not a personal token

The connection uses a GitHub App. A personal access token belongs to a person and stops working when they leave, which turns a documentation site into an incident on somebody’s last day.

Conflicts

If a page changed on the default branch while a branch was open, the mismatch is detected and nothing is overwritten. You get the diff and three choices: yours, theirs, or merge by hand.

The connection screen

It shows the last successful sync, the latest error if there is one, and a reconnect action. When a connection needs attention, the state says needs_reconnect, which covers an expired credential, a revoked installation, or a repository that moved.

Checks on a pull request

Run the linter in your own workflow, so broken documentation fails a pull request instead of reaching a reader:

- run: npx staleless lint docs
- run: npx staleless impact --changed "${{ steps.diff.outputs.files }}"

lint needs no token and no network, so it works on a pull request from a fork. See the CLI.

Which files Staleless reads

Inside the folder you chose:

nav.yaml  variables.yaml  search.yaml  redirects.yaml
glossary.yaml  style.yaml  pages/  snippets/

Everything else in your repository is ignored.