# Homebrew tap for Rivet

Homebrew expects a **separate** Git repository named `homebrew-<tap>`. For `brew tap yourname/rivet`, create:

`https://github.com/yourname/homebrew-rivet`

## Layout

```
homebrew-rivet/
  Formula/
    rivet.rb
  README.md   # optional
```

## Generate `rivet.rb`

After you publish a GitHub Release (tag `v…`, assets + `SHA256SUMS.txt` from CI):

```bash
cd /path/to/rivet
chmod +x dev/scripts/update_homebrew_formula.sh

# Uses version from Cargo.toml and repository URL for GitHub owner/repo
./dev/scripts/update_homebrew_formula.sh

# Or if the app lives under another fork:
GITHUB_REPOSITORY=panchenkoai/rivet ./dev/scripts/update_homebrew_formula.sh
```

Copy the generated file:

```bash
cp packaging/homebrew/rivet.rb ../homebrew-rivet/Formula/rivet.rb
```

Commit and push the tap repo, then:

```bash
brew tap yourname/rivet
brew install rivet
brew test rivet
```

## One-time tap setup

1. Create an empty repo `yourname/homebrew-rivet` on GitHub.
2. Add `Formula/rivet.rb` (generated as above).
3. Optional: add a short README describing `brew tap yourname/rivet`.

## Automatic updates after each release

The [Release workflow](../../.github/workflows/release.yml) always regenerates `packaging/homebrew/rivet.rb` from `artifacts/SHA256SUMS.txt` (no extra download).

To **push** that formula into the tap automatically:

1. Create a GitHub repo named **`homebrew-rivet`** under the **same account/org** as Rivet  
   (e.g. `panchenkoai/homebrew-rivet` next to `panchenkoai/rivet`). Initialize with a README or leave empty; default branch `main` is fine.

2. In the **rivet** repo: **Settings → Secrets and variables → Actions → New repository secret**  
   - Name: `HOMEBREW_TAP_GITHUB_TOKEN`  
   - Value: a [fine-grained PAT](https://github.com/settings/tokens?type=beta) or classic PAT with **Contents: Read and write** on **`homebrew-rivet` only** (not the whole account if you can avoid it).

3. On every successful Release (tag `v*`), the workflow commits and pushes `Formula/rivet.rb` to `homebrew-rivet`.

If the secret is missing, the release still completes; only the tap push step is skipped.

### Troubleshooting: `Authentication failed` / `Invalid username or token`

The job clones `https://github.com/<owner>/homebrew-rivet` with **`HOMEBREW_TAP_GITHUB_TOKEN`**. That error means GitHub rejected the token, not the workflow syntax.

1. **Regenerate the secret** in the **rivet** repo: Settings → Secrets and variables → Actions → edit `HOMEBREW_TAP_GITHUB_TOKEN`.
2. **Fine-grained PAT:** Resource owner = org or user that owns `homebrew-rivet` → Repository access = **only** `homebrew-rivet` → Permission **Contents: Read and write**. Expiration: choose a date you will renew.
3. **Classic PAT:** scope **`repo`** (or at least repo access to that repository). SSO: if the org uses SAML, **Authorize** the token for the org.
4. **Paste:** no extra spaces or newlines when saving the secret.
5. Confirm the tap repo exists: `https://github.com/<owner>/homebrew-rivet` (same `<owner>` as `github.repository_owner` in the workflow).

Until the token is fixed, update the tap manually (copy `packaging/homebrew/rivet.rb` after release, or run `dev/scripts/update_homebrew_formula.sh` locally).

### Manual / local refresh

Same as before — download checksums from the release or use a local `SHA256SUMS.txt`:

```bash
./dev/scripts/update_homebrew_formula.sh --tag v0.2.0-beta.2 --sums-file path/to/SHA256SUMS.txt
```
