mirror of
https://github.com/Sea-Haven-Industries/engineering-handbook.git
synced 2026-10-04 19:32:10 +00:00
735b407017
Partner engineering teams need the standards without access to this repo, which contains internal repo names, account identifiers, and migration history. Adds eight simplified pages, one per Confluence page, plus an internal README with source mapping and exclusions. 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 Sea Haven contact rather than working around it.
|