Encore OS — Documentation

Created: 2026-04-28
Purpose: Tracks manual GitHub and Supabase configuration steps that cannot be done through code and must be completed by a repository administrator.

1. Supabase Remote Migration Repair (URGENT)

The Dev Supabase project has 9 remote migrations that are not present in the local repository. The supabase-ci dryrun-push job will continue to fail until this is resolved. Symptoms: supabase db push --dry-run reports:

Remote migration versions not found in local migrations directory.
...
supabase migration repair --status reverted 20260427164732 20260427164801 20260427164838 20260427174353 20260427174436 20260427174519 20260427174534 20260428163225 20260428163257

Resolution options (choose one):

Option A: Mark remote migrations as reverted (if they are genuinely not needed)

supabase link --project-ref <SUPABASE_DEV_PROJECT_ID> --yes
supabase migration repair --status reverted \
  20260427164732 20260427164801 20260427164838 \
  20260427174353 20260427174436 20260427174519 \
  20260427174534 20260428163225 20260428163257

Option B: Pull the remote migrations into the repo (if they contain real schema changes)

supabase link --project-ref <SUPABASE_DEV_PROJECT_ID> --yes
supabase db pull
# Review the pulled migrations, then commit them

Option C: Manually trigger `supabase-sync-from-dev` workflow

Go to Actions → Supabase sync from Dev → Run workflow to capture any real drift as a proper migration PR. Reference: docs/development/supabase/SUPABASE_CLI_LOCAL_WORKFLOW.md

2. Branch Protection Rules

Configure branch protection on dev, main, and production branches to require CI to pass before merge. Go to: Repository Settings → Branches → Add branch protection rule

For `dev`:

Require a pull request before merging
Require status checks to pass before merging
- Required checks: governance, quality, tests, build-and-smoke
Require branches to be up to date before merging
Do not allow bypassing the above settings

For `main`:

Require a pull request before merging
Require status checks to pass before merging
- Required checks: governance, quality, tests, build-and-smoke
Require linear history
Do not allow bypassing the above settings

For `production`:

Require a pull request before merging
Require status checks to pass before merging
- Required checks: governance, quality, tests, build-and-smoke, migration-lane (from supabase-promote-pr)
Require linear history
Restrict who can push to matching branches (admins only)
Do not allow force pushes
Do not allow bypassing the above settings

3. GitHub Secret Scanning

Enable GitHub’s native secret scanning to prevent accidentally committed credentials. Go to: Repository Settings → Security → Advanced Security

Enable Dependabot alerts
Enable Secret scanning
Enable Push protection (blocks pushes containing detected secrets)

This has zero CI minute cost — it runs on GitHub’s infrastructure.

4. Review Open Dependabot PRs

Several Dependabot PRs are open for GitHub Actions version bumps. Review and merge or close these:

PR	Title	Risk
#180	`actions/upload-artifact` from 4 to 7	Low — v7 is compatible; standardize all workflows before merging
#179	`marocchino/sticky-pull-request-comment` from 2 to 3	Low — check changelog
#178	`peter-evans/create-pull-request` from 6 to 8	Medium — check for breaking API changes

Note: Before merging #180, update all remaining upload-artifact@v4 references in the codebase to @v7 so the version is consistent. Currently all workflows use @v4.

5. Verify Sentry Auth Token

The SENTRY_AUTH_TOKEN secret is referenced in build.yml (in the build-and-smoke job) but only runs on push to main or production. Verify the token is still valid: Go to: Repository Settings → Secrets and variables → Actions

Confirm SENTRY_AUTH_TOKEN exists and is not expired
If expired: Generate a new token at https://sentry.io/settings/account/api/auth-tokens/
The Sentry step now only fires on post-merge pushes to main/production, not on PRs

6. CODEOWNERS Usernames

The .github/CODEOWNERS file created in this audit uses @JeremyBloom as a placeholder for all critical paths. Update this with the correct GitHub username(s) or team slugs (@org/team-name) for each path. File: .github/CODEOWNERS

7. Required Secrets Reference

The following secrets are required for full CI functionality. Verify all are configured in Repository Settings → Secrets and variables → Actions:

Secret	Used By	Notes
`TURBO_TOKEN`	`build.yml`	Optional; enables Vercel Remote Cache for Turborepo
`TURBO_TEAM`	`build.yml`	Optional; paired with `TURBO_TOKEN`
`CODECOV_TOKEN`	`build.yml`	Coverage upload; non-blocking if missing
`SENTRY_AUTH_TOKEN`	`build.yml`	Release tagging; only fires on `main`/`production` push
`SUPABASE_ACCESS_TOKEN`	`supabase-ci.yml`, `supabase-deploy-*.yml`, `supabase-sync-from-dev.yml`	Required for remote Supabase operations
`SUPABASE_DEV_DB_PASSWORD`	`supabase-ci.yml`, `supabase-deploy-dev.yml`, `supabase-sync-from-dev.yml`	Dev project DB password
`SUPABASE_DEV_PROJECT_ID`	`supabase-ci.yml`, `supabase-deploy-dev.yml`, `supabase-sync-from-dev.yml`	Dev project ref
`SUPABASE_PROD_DB_PASSWORD`	`supabase-ci.yml`, `supabase-deploy-prod.yml`, `supabase-bootstrap-prod.yml`	Prod DB password
`SUPABASE_PROD_PROJECT_ID`	`supabase-ci.yml`, `supabase-deploy-prod.yml`, `supabase-bootstrap-prod.yml`	Prod project ref
`SUPABASE_PROD_DB_URL`	`supabase-bootstrap-prod.yml`	Optional; pool URI for seed parity check
`E2E_VITE_SUPABASE_URL`	`e2e-full.yml`	Staging Supabase URL for full E2E
`E2E_VITE_SUPABASE_PUBLISHABLE_KEY`	`e2e-full.yml`	Staging anon key
`TEST_USER_ADMIN_EMAIL`	`e2e-full.yml`	E2E test admin credentials
`TEST_USER_ADMIN_PASSWORD`	`e2e-full.yml`	E2E test admin credentials

Status Tracking

Action	Owner	Status	Notes
Supabase remote migration repair	Jeremy	Done	Repaired 9 remote-only versions; local and CI `dryrun-push` now pass
Branch protection: `dev`	Jeremy	Pending	After next clean CI run
Branch protection: `main`	Jeremy	Pending	After next clean CI run
Branch protection: `production`	Jeremy	Pending	After next clean CI run
Enable secret scanning + push protection	Jeremy	Pending	No CI cost
Review Dependabot PRs #178-180	Jeremy	Pending	Low risk
Verify Sentry auth token	Jeremy	Pending	Only needed for production deploys
Update CODEOWNERS usernames/teams	Jeremy	Pending	After team is defined

Start Here

Module Engineering Snapshots

Canonical AI Governance

Architecture

Integrations

Development

Decision Guides

Database

Module Reference

Testing

Migration

Operations

Governance & Security

Platform Internals

CI/CD Manual Follow-Up Actions

1. Supabase Remote Migration Repair (URGENT)

Option A: Mark remote migrations as reverted (if they are genuinely not needed)

Option B: Pull the remote migrations into the repo (if they contain real schema changes)

Option C: Manually trigger `supabase-sync-from-dev` workflow

2. Branch Protection Rules

For `dev`:

For `main`:

For `production`:

3. GitHub Secret Scanning

4. Review Open Dependabot PRs

5. Verify Sentry Auth Token

6. CODEOWNERS Usernames

7. Required Secrets Reference

Status Tracking

​1. Supabase Remote Migration Repair (URGENT)

​Option A: Mark remote migrations as reverted (if they are genuinely not needed)

​Option B: Pull the remote migrations into the repo (if they contain real schema changes)

​Option C: Manually trigger supabase-sync-from-dev workflow

​2. Branch Protection Rules

​For dev:

​For main:

​For production:

​3. GitHub Secret Scanning

​4. Review Open Dependabot PRs

​5. Verify Sentry Auth Token

​6. CODEOWNERS Usernames

​7. Required Secrets Reference

​Status Tracking

1. Supabase Remote Migration Repair (URGENT)

Option A: Mark remote migrations as reverted (if they are genuinely not needed)

Option B: Pull the remote migrations into the repo (if they contain real schema changes)

Option C: Manually trigger `supabase-sync-from-dev` workflow

2. Branch Protection Rules

For `dev`:

For `main`:

For `production`:

3. GitHub Secret Scanning

4. Review Open Dependabot PRs

5. Verify Sentry Auth Token

6. CODEOWNERS Usernames

7. Required Secrets Reference

Status Tracking