- 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
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.
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.
