# CI/CD and Deployments

## Rules

- Every deployable repo has a CI workflow and a deploy workflow. A project is not production-ready without them.
- Nobody deploys from a workstation. Only the pipeline deploys, and it deploys a reviewed commit.
- GitHub Actions is the CI/CD platform.

## CI

- CI runs on every pull request to `main`.
- A PR cannot merge until the required CI check passes.
- Lint, formatting, type checks, and tests run in CI.

## Environments and deploys

| Environment | Deployed when | Approval |
|---|---|---|
| `dev` | A PR merges to `main` | None |
| `prod` | A person publishes a GitHub Release | Required |

### Releasing to production

A person cuts a release from `main` after the change has been verified in dev:

```bash
gh release create vX.Y.Z --target main --generate-notes
```

Releases are never created by a workflow. After the release is published, the production deploy waits for a Sea Haven approver.

### Rollback

Re-run the deploy workflow manually (`workflow_dispatch`) at the previous release tag and have it approved. Do not roll back by reverting infrastructure code.

### Hotfixes

When production is broken and the fix cannot wait for `main`:

```bash
git fetch --tags
git checkout -b hotfix/describe-the-break v1.2.3
# commit and push, or open a PR targeting the hotfix branch
gh release create v1.2.4 --target hotfix/describe-the-break --generate-notes
# after the prod deploy is approved and verified:
# merge hotfix/describe-the-break into main
```

### Verify the live system

A green workflow run is not proof of a working deploy. Check the live system: health endpoints report the new version, and the application behaves as expected.

## Workflow conventions

- Workflow files are kebab-case, one deploy workflow per deployable: `deploy-web.yaml`, `deploy-api.yaml`.
- Pin every GitHub Action and reusable workflow to a full commit SHA, with the version in a comment:

  ```yaml
  uses: actions/checkout@<full-commit-sha> # v4.1.0
  ```

  Never reference a branch or a tag alone. Automated update PRs move the pins forward.
- Deploys authenticate to AWS with OIDC roles. Never use long-lived AWS access keys in GitHub.
- Deploy jobs use `cancel-in-progress: false`. Cancelling a deploy halfway leaves the environment half-updated. CI jobs may cancel superseded runs.
- Do not hardcode bucket names, distribution IDs, or function names in workflow YAML. Read them from configuration.

## Repository settings

Sea Haven manages repository settings, branch protection, secret scanning, and Dependabot alerts. If a setting blocks your work, raise it with your technical point of contact rather than working around it.