Skip to content
Raw Markdown

Troubleshoot git and publishing

Start from the symptom, reproduce it locally when possible, and confirm the published version after the fix.

The context check failed

Run the same validation in the checkout for a more detailed error:

cassis context check

Common causes are malformed YAML, an unknown or misspelled field, a missing required field, an invalid domain path, or a reference to a domain that is not in the tree. Fix the named file, then run cassis context fmt and cassis context check again.

Cassis keeps the previous published version when an import fails.

Cassis cannot find the context

The complete tree must be under the project’s configured Path, cassis/ by default, on the default branch. If every reported path has an unexpected extra directory, update Path to the actual location or move the tree once and review that change before merging.

No pull-request check appeared

Under Organization → GitHub, confirm that:

  • the Cassis App installation includes the repository;
  • the project points to the correct owner/name;
  • Cassis checks are enabled for Cassis-created branches when the branch starts with cassis/.

A merge did not publish

On GitHub, check the Cassis sync result on the default-branch commit. On another provider, check that the default-branch job ran cassis context upload with the correct project ID and API key.

A 403 from GitHub usually means the App no longer has Contents and Pull requests write access. A 404 usually means the repository was renamed, deleted, or has no default branch.

Publishing or merging fails with a repository error

The message starts with “Cassis cannot reach the repository”. The Cassis GitHub App was uninstalled or disconnected, or GitHub refused it access to the repository. Nothing is published until Cassis can write to the repository again, so the repository stays the source of truth. A branch’s pull request banner shows the same message.

An organization admin fixes it under Settings → GitHub: reconnect the GitHub App and confirm its installation includes the repository. To publish without the repository, remove it from the project under Project configuration instead.

The upload refuses uncommitted files

cassis context upload and cassis schema push exit 2 when the context files under cassis/ differ from HEAD, and list the files. Commit them, or discard the changes, and run the command again. The same exit means the directory is not a git checkout with a commit, or git is not installed: CI images need it, and the python:3.12-slim image does not have it. See Set up CI.

Retry an import without another push

Re-run the default-branch job that calls cassis context upload, or run the same command from a checkout of the default-branch commit.

A forced re-import overwrites unpublished in-app edits, like any repository import. Check Unpublished changes first if both editing paths have been used.

After any recovery, confirm the expected version with cassis status or get_project_status. Exact validation messages and exit codes are in the CLI reference.