mirror of
https://github.com/Sea-Haven-Industries/engineering-handbook.git
synced 2026-10-03 10:23:24 +00:00
56c0e76fd5
Partner teams need the Sentry setup and privacy rules, which only exist in individual Jira tickets. Also syncs index wording edits already made on the published Confluence page. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01UP6j3hYgoVqjKZwC3XB9ay
69 lines
2.6 KiB
Markdown
69 lines
2.6 KiB
Markdown
# 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.
|