# History and safe deploys

Local git keeps history on one computer. GitHub keeps it safe off the computer, shows every change, and can put the app live automatically, with tests first.

## Day one: git
- `git init` before the first file. Add `.gitignore`: `node_modules/`, `.wrangler/`, `.dev.vars`, `.env`, `*.log`, screenshots and scratch files.
- Commit every working change: `git commit -m "Bottle timer with burp breaks"`. Plain-English messages; the user may read them.
- Never commit secrets. Local secrets go in `.dev.vars` (gitignored); live ones via `npx wrangler secret put NAME`.

## GitHub (offer it once the first version works)
Ask first: "Shall I keep a private copy on GitHub? It means a backup, a history you can browse, and deploys that run tests first."

```sh
gh auth status                       # are they signed in?
gh repo create my-app --private --source=. --push
```

- Private by default. Public only if the user wants it and nothing private is in the history.
- Before the first push, check the whole history for secrets and real data: `git log -p | grep -iE "token|secret|password|@"`.

## Deploys from GitHub: pick one

**A. Workers Builds (simplest).** In the Cloudflare dashboard: Workers & Pages → the Worker → Settings → Builds → connect the GitHub repo. Every push to `main` builds and deploys. No tokens to manage. Set the deploy command to the project's own script if it runs migrations first (e.g. `npm run deploy`).

**B. GitHub Actions (more control).** `.github/workflows/deploy.yml` runs tests, then deploys:

```yaml
name: Deploy
on:
  push:
    branches: [main]
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6
      - uses: actions/setup-node@v4
        with: { node-version: 22 }
      - run: npm ci
      - run: npm test
      - uses: cloudflare/wrangler-action@v4
        with:
          apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }}
          accountId: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
          command: deploy
```

- Token: Cloudflare dashboard → Account API tokens → Create Token → "Edit Cloudflare Workers", scoped to this account. Add both values with `gh secret set CLOUDFLARE_API_TOKEN` and `gh secret set CLOUDFLARE_ACCOUNT_ID` (the user pastes them; never print them).
- If D1 migrations exist, apply them in the workflow before deploying (`wrangler d1 migrations apply DB --remote`), or make `npm run deploy` do both in that order.

## The house rule still applies
With automatic deploys, **merging to `main` is going live**. Work on a branch, show screenshots, and ask before merging. A pull request is a good place to show what changed.

## Seeing and undoing deploys
```sh
npx wrangler deployments list       # what went live, when
npx wrangler versions list          # recent versions
npx wrangler rollback               # back to the previous version (asks which)
npx wrangler versions upload        # upload without going live; gives a preview address
```
- Rollback restores code, **not data**. If a release changed the database, roll forward with a fix instead, or restore the database (see data-and-sync.md).
- After any deploy: load the live site, check the version shown in Settings, and check error reports.

## Release checklist
1. Tests pass locally (and in CI).
2. Screenshots shown; the user said yes.
3. Service worker version bumped (if the app is installable).
4. Migrations applied remotely, before the code that needs them.
5. Deploy. Check the live site and errors.
6. Tell the user how phones pick it up ("Settings → Check for updates").
