Skip to main content
By default, unch is entirely local. Remote indexing through GitHub Actions is an optional layer on top.

Stay local by default

You only need CI when you want a shared published state for the repository.

Warm restores

Published remote state includes filehashes.db, so warm reindex paths can reuse the same file-hash cache.

Latest compatible state

unch search and unch remote sync restore only state that matches the local binary schema.

​
When remote indexing helps

  • Multiple people search the same repository
  • You want the shared index to stay current without manual local reindexing
  • You want CI to publish one canonical snapshot for the repo state

​
How the workflow works

1

Generate the workflow

unch create ci writes .github/workflows/unch-index.yml.
2

Bind the checkout

unch bind ci <github-repo-url> records the remote workflow in the local manifest.
3

Publish shared state

GitHub Actions builds and publishes the search state for the repository.
4

Restore when needed

unch search and unch remote sync restore the latest compatible published state when needed.

​
What gets published

The remote workflow publishes:
  • index.db
  • manifest.json
  • filehashes.db
That lets warm restore and warm reindex paths reuse the same file-hash cache instead of starting from scratch every time.

​
Local reindex behavior

Running unch index locally on a repository that is bound to remote CI detaches the manifest from remote mode and switches it back to local-only state. After a local reindex, run unch bind ci <github-repo-url> again if you want that checkout to follow remote updates.
Use remote indexing for shared state, not as a requirement for basic local search. The normal unch flow still works fully without CI.