# GitHub sign-in and device sync setup

The application code, local migration, row-level security, and sync engine are already included. This setup connects them to a free Supabase project.

## 1. Create the Supabase project

1. Sign in at [supabase.com](https://supabase.com/).
2. Create a new project named `ko-do-list` on the Free plan.
3. Wait for the database to finish provisioning.

## 2. Install the database migration

1. In Supabase, open **SQL Editor**.
2. Create a new query.
3. Copy the entire contents of [`supabase/migrations/202608170001_create_sync_items.sql`](../supabase/migrations/202608170001_create_sync_items.sql).
4. Run the query once.

The migration creates one local-first sync table, strict per-user Row Level Security policies, stale-write protection, and Realtime updates. It is safe to run again.

## 3. Create the GitHub OAuth application

1. On GitHub, open **Settings → Developer settings → OAuth Apps**.
2. Select **New OAuth App**.
3. Use these values:

   - **Application name:** `Ko-Do List`
   - **Homepage URL:** `https://codykoinabox.github.io/ko-do-list/`
   - **Authorization callback URL:** copy the callback URL shown under **Supabase → Authentication → Sign In / Providers → GitHub**. It looks like `https://YOUR_PROJECT_REF.supabase.co/auth/v1/callback`.

4. Register the application.
5. Copy the Client ID and generate a Client Secret.

Never put the GitHub Client Secret in this repository, a Vite environment variable, GitHub Pages, or a chat message.

## 4. Enable GitHub in Supabase

1. In Supabase, open **Authentication → Sign In / Providers → GitHub**.
2. Enable the provider.
3. Paste the GitHub Client ID and Client Secret there.
4. Save.

Supabase stores and uses the secret server-side. Ko-Do never receives it.

## 5. Configure allowed redirects

In **Supabase → Authentication → URL Configuration**, set:

- **Site URL:** `https://codykoinabox.github.io/ko-do-list/`
- **Redirect URLs:**
  - `https://codykoinabox.github.io/ko-do-list/`
  - `http://localhost:5173/`

If Vite starts on a different local port, add that exact local URL while testing.

## 6. Configure local development

Copy `.env.example` to `.env.local`, then replace the placeholders with **Supabase → Project Settings → API** values:

```dotenv
VITE_SUPABASE_URL=https://YOUR_PROJECT_REF.supabase.co
VITE_SUPABASE_PUBLISHABLE_KEY=sb_publishable_YOUR_KEY
```

These two browser configuration values are public by design. Never use the `service_role` key in the web app.

Restart the development server after changing `.env.local`:

```powershell
npm run dev
```

## 7. Configure GitHub Pages

In the GitHub repository, open **Settings → Secrets and variables → Actions → Variables** and create:

- `VITE_SUPABASE_URL`
- `VITE_SUPABASE_PUBLISHABLE_KEY`

Use the same public values from the local file. The Pages workflow passes them to Vite at build time.

## Verification checklist

1. Create a local task while signed out.
2. Select **Sync → Continue with GitHub**.
3. Confirm the local task still exists after returning from GitHub.
4. Open Ko-Do in another browser and sign in with the same account.
5. Confirm the task appears, edit it, and verify the first browser receives the change.
6. Delete a task on one device and verify it does not reappear on the other.