> ## Documentation Index
> Fetch the complete documentation index at: https://unch.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# GitHub Actions

> Step-by-step guide to setting up the unch remote index workflow in your repository.

<Steps>
  <Step title="Create the workflow file">
    ```bash theme={null}
    unch create ci
    ```

    This writes `.github/workflows/unch-index.yml`.

    To scaffold into another repository:

    ```bash theme={null}
    unch create ci --root ../other-repo
    ```
  </Step>

  <Step title="Commit the workflow">
    ```bash theme={null}
    git add .github/workflows/unch-index.yml
    git commit -m "Add unch remote index workflow"
    ```
  </Step>

  <Step title="Bind the local manifest">
    ```bash theme={null}
    unch bind ci https://github.com/owner/repo
    ```

    You can also bind directly to a workflow URL:

    ```bash theme={null}
    unch bind ci https://github.com/owner/repo/actions/workflows/unch-index.yml
    ```
  </Step>

  <Step title="Push and verify">
    Push the commit and confirm that the workflow succeeds in the repository Actions tab.
  </Step>

  <Step title="Force sync if needed">
    ```bash theme={null}
    unch remote sync
    ```

    After the first successful publish, `unch search` can auto-refresh from remote when a newer version exists.
  </Step>
</Steps>

## Workflow inputs

The generated workflow supports manual `workflow_dispatch` inputs:

* `force_rebuild`
* `skip_remote_restore`
* `skip_publish`

These are useful for bootstrap flows, debugging, and controlled republish runs.

<Tabs>
  <Tab title="Repository URL bind">
    ```bash theme={null}
    unch bind ci https://github.com/owner/repo
    ```
  </Tab>

  <Tab title="Workflow URL bind">
    ```bash theme={null}
    unch bind ci https://github.com/owner/repo/actions/workflows/unch-index.yml
    ```
  </Tab>
</Tabs>

## Bootstrap flows

If you want to continue gracefully when no remote artifact exists yet:

```bash theme={null}
unch remote sync --allow-missing
```

With `--allow-missing`, a missing or incompatible remote index prints a notice and exits cleanly instead of failing the flow.

## Schema upgrades

When a release changes indexing or storage compatibility:

1. rerun the repository’s `unch-index.yml` workflow
2. let CI republish a compatible `index.db`, `manifest.json`, and `filehashes.db`
3. run `unch remote sync` or just search again locally

<AccordionGroup>
  <Accordion title="What does the workflow publish?">
    The generated workflow publishes `index.db`, `manifest.json`, and `filehashes.db`.

    That gives later restores both the active index and the warm file-hash cache.
  </Accordion>

  <Accordion title="What if no remote artifact exists yet?">
    Use `unch remote sync --allow-missing` during bootstrap or first-run CI flows.

    That way a missing artifact does not fail the entire flow before the first publish exists.
  </Accordion>

  <Accordion title="What should I rerun after an incompatible release?">
    Rerun `.github/workflows/unch-index.yml` so the repository republishes state compatible with the upgraded binary.
  </Accordion>
</AccordionGroup>