mirror of
https://github.com/Sea-Haven-Industries/engineering-handbook.git
synced 2026-09-30 22:03:13 +00:00
Adam Moussa
8ceee9b652
Exact pins remain (reproducibility) but the pinned version is kept current by Dependabot version updates gated by CI + dependency review, not by a number frozen in the handbook. Blanket dependabot ignore entries are banned; version-specific ignores only, commented and temporary. Bundled-dep vulnerabilities are a prompt to advance the pin, never to dismiss the alert.
114 lines
3.4 KiB
Markdown
114 lines
3.4 KiB
Markdown
# GitHub Standards
|
|
|
|
## Repository Defaults
|
|
|
|
- Default branch: `main`
|
|
- Every repo gets a one-line description
|
|
- Default to `private` visibility for org repos
|
|
- Dependabot alerts and security updates enabled on all active repos
|
|
- Org-level defaults auto-enable alerts and security updates on new repos
|
|
- Every repo with dependencies gets a `.github/dependabot.yml` for weekly version updates
|
|
|
|
## Dependabot Configuration
|
|
|
|
Every active repo with package dependencies must have a `.github/dependabot.yml` that covers all relevant ecosystems.
|
|
|
|
### Pinning Principle
|
|
|
|
Exact pins are for reproducibility, not for freezing time. The pinned version is kept current by Dependabot version updates gated by CI and dependency review — never by a version number written in documentation.
|
|
|
|
- Never add a blanket `ignore` entry for a dependency. If a specific release is broken, ignore that release only (`versions: ["x.y.z"]`), with a comment, and remove the entry once a fixed release ships.
|
|
- Never dismiss a vulnerability alert as "waiting for upstream" without a linked follow-up that advances the pin when the fix ships.
|
|
- If a bump PR fails CI, the gate worked — leave the bad release unmerged and take the next one.
|
|
|
|
### Ecosystem Selection
|
|
|
|
Choose ecosystems based on what dependency files exist in the repo:
|
|
|
|
| File | Ecosystem |
|
|
|------|-----------|
|
|
| `package.json` | `npm` |
|
|
| `requirements.txt` | `pip` |
|
|
| `.csproj` | `nuget` |
|
|
| `.github/workflows/*.yml` | `github-actions` |
|
|
|
|
### Standard Templates
|
|
|
|
**Single ecosystem (npm or pip):**
|
|
|
|
```yaml
|
|
version: 2
|
|
updates:
|
|
- package-ecosystem: "npm" # or "pip", "nuget", "github-actions"
|
|
directory: "/"
|
|
schedule:
|
|
interval: "weekly"
|
|
```
|
|
|
|
**SAM project with per-function `requirements.txt`:**
|
|
|
|
Add a separate entry for each directory containing a `requirements.txt`:
|
|
|
|
```yaml
|
|
version: 2
|
|
updates:
|
|
- package-ecosystem: "pip"
|
|
directory: "/src/processor"
|
|
schedule:
|
|
interval: "weekly"
|
|
- package-ecosystem: "pip"
|
|
directory: "/src/receiver"
|
|
schedule:
|
|
interval: "weekly"
|
|
```
|
|
|
|
**Mixed ecosystems (e.g., CDK in JS with Python Lambdas, or repos with GitHub Actions):**
|
|
|
|
Add one entry per ecosystem/directory:
|
|
|
|
```yaml
|
|
version: 2
|
|
updates:
|
|
- package-ecosystem: "npm"
|
|
directory: "/"
|
|
schedule:
|
|
interval: "weekly"
|
|
- package-ecosystem: "pip"
|
|
directory: "/src"
|
|
schedule:
|
|
interval: "weekly"
|
|
- package-ecosystem: "github-actions"
|
|
directory: "/"
|
|
schedule:
|
|
interval: "weekly"
|
|
```
|
|
|
|
### Merging Dependabot PRs
|
|
|
|
- **Patch and minor bumps:** Safe to merge without review in most cases
|
|
- **Major version bumps:** Review changelog for breaking changes before merging
|
|
- When merging multiple Dependabot PRs, merge one at a time — subsequent PRs will auto-rebase
|
|
|
|
## Branch Protection
|
|
|
|
- Require a PR for merges to `main` (no direct push)
|
|
- No force push to `main`
|
|
- No branch deletion for `main`
|
|
|
|
## Repo Hygiene
|
|
|
|
- Delete feature branches after merge
|
|
- Archive repos that are no longer actively developed (close issues first)
|
|
- Don't delete repos unless truly disposable
|
|
- Scrub all company-specific info from git history before making any repo public
|
|
|
|
## Public Repos
|
|
|
|
Before making a repo public, verify the entire git history contains no:
|
|
|
|
- Phone numbers or customer data
|
|
- API subdomains or internal URLs
|
|
- Webhook endpoints
|
|
- Employee names or internal identifiers
|
|
|
|
If sensitive data was committed at any point, start fresh with a clean `git init` rather than rewriting history.
|