Change management
Last reviewed 2026-05-18
Purpose
Ensure that every change to HiringCoachAI production systems is reviewed, tested, documented, and reversible.
Branching and release
- Main branch:
master - Feature branches:
feat/,fix/,chore/*; branched frommaster - Preview deployments: Vercel can deploy pull requests to unique preview URLs when the PR workflow is used.
- Production: Merging to
mastertriggers a production build on Vercel - Rollback: Vercel "Instant Rollback" to any prior deploy; target rollback time ≤5 min
Current change checks
Current change control is built from local pre-push checks, manual GitHub workflows, CODEOWNERS ownership records, and Security Officer approval before production release.
1. Local pre-push gate: a pre-push git hook runs a fast local-checks command unless explicitly bypassed with an opt-out environment variable. 2. Fast local checks: the local-checks command runs TypeScript, changed-file ESLint, API-validation delta, unsafe-fetch delta, AI retention-flag delta, and compliance-document audits when relevant files change. 3. Full local checks: a full local-checks command adds the production build before release or major changes. 4. Major-change dependency support review: major changes include a review of required third-party libraries, SDKs, platform runtimes, and managed-service integrations before production release. Unsupported or end-of-life dependencies must be upgraded, replaced, removed from release scope, or covered by a documented time-bound exception. 5. GitHub checks: manual CI and scheduled/manual security workflows can run typecheck, lint, build, smoke, npm audit, Semgrep, CodeQL, SBOM, patch verification, unauthenticated ZAP baseline DAST, and compliance-audit jobs. 6. Documentation-review drills: drills covering business continuity, disaster recovery, joiner/mover/leaver, vendor, and change can be run locally or through the manual security workflow; each archives a dated record in the internal audit evidence set. 7. Code ownership: CODEOWNERS routes sensitive paths to the Security Officer when GitHub PR review is used.
Branch protection
master is the only deploy branch. Current controls are:
| Control | Mechanism | Verification |
|---|---|---|
| Direct push control | Push access is restricted to the Security Officer via repository access control. Major changes follow this change management policy. | Repo access settings; CODEOWNERS file |
| Code ownership | CODEOWNERS owns * and sensitive paths, routing PR review to the Security Officer when the PR workflow is used. | CODEOWNERS file |
| Local quality checks | Pre-push hook runs fast local checks; a full local-checks command is available. | Internal hook and script |
| Manual GitHub workflows | CI and security jobs are available through workflow dispatch. | GitHub Actions workflows |
| Force-push / deletion control | Prohibited by policy on master. | Internal change governance review |
| Linear history (preferred) | Preferred on master. | Internal change governance review |
Branch ownership and protection. CODEOWNERS routes sensitive paths to the Security Officer; force-push and direct deletion of protected branches are prohibited by policy and reviewed under change governance.
Compensating controls at current scale:
1. Restricted personnel: Source-code, customer-data, production, and vendor-dashboard access is restricted to authorized personnel with Security Officer approval. 2. CODEOWNERS ownership: all paths are owned by the Security Officer, with additional sensitive-path routing. 3. Local checks: pre-push and full local checks provide repeatable quality gates before push or release. 4. Audit review: git log --pretty=fuller is reviewed during internal audit for out-of-band commits.
Change categories
| Category | Examples | Approval | Notification |
|---|---|---|---|
| Standard | Bug fixes, UI tweaks, copy, dependency patch bumps | Reviewer approval | None |
| Normal | New features, schema additions, new API routes | Reviewer + Engineering Lead | Changelog entry |
| Major | Breaking API changes, data migration, auth changes, pricing changes | Security Officer + Engineering Lead | Customer notice using risk-appropriate timing and channels |
| Emergency | Security incident, production outage, critical bug | Security Officer (retroactive if needed) | Post-incident customer notice within 24 h; status page |
Deployment windows
- Standard/normal changes: any time; deploys are rolled out progressively by Vercel.
- Major changes: deployed during low-traffic windows (default: weekdays 02:00-06:00 US-Eastern) or behind feature flags with gradual rollout.
- Emergency changes: any time, with post-deploy verification and monitoring.
HiringCoachAI designs updates to avoid customer impact. Higher-risk changes use low-traffic windows, progressive rollout, feature flags where appropriate, post-deploy monitoring, and rollback to limit customer impact if an issue occurs.
Customer notification
- Major: Customers are notified when a major change materially affects customer security, privacy, data handling, authentication/access-control behavior, retention/deletion behavior, AI provider or prompt-handling posture, sub-processor use, or breaking API behavior. Timing and channels are risk-based rather than a fixed advance-notice window. Channels may include customer email, in-app notice, or status page. A copy of every major-change notification is filed in the internal audit archive for customer-security-review evidence.
- Emergency / breaking: Post-hoc notice within 24 h where appropriate; root cause and remediation published when disclosure is warranted. Recorded in the internal emergency-change register.
- Security patches: Generally silent; disclosed in release notes or on
/statusif the patch was incident-driven.
Version support
HiringCoachAI is a continuously-delivered cloud-hosted service; there are no versioned customer installs. We maintain a single production version; all customers are on the current release. Routine product updates are communicated through normal product channels when customer action or material customer impact exists; major-impact notices follow the criteria above. HiringCoachAI performs service updates within the cloud-hosted environment; institutions do not need to install packages, schedule local deployment windows, change endpoint software, or provide technical staff to complete routine updates.
Configuration management
- Runtime baselines are managed through Vercel and Google Cloud / Firebase managed services rather than first-party server or endpoint images.
- Application configuration is held in environment variables managed by the hosting platform
- Infrastructure configuration (Firestore Security Rules, Firestore indexes, Firebase configuration, hosting-platform configuration, framework configuration) is version-controlled
- All configuration changes are tracked in git
- Secrets are never committed; environment files are gitignored; secrets rotation cadence is held internally
Emergency-change log
Emergency changes are recorded in a restricted administrator register backed by Firestore and audit-log events. Each record captures the date/time, summary, severity, systems affected, reason for bypassing the normal workflow, authorization timing, authorizer, implementer, verification steps, rollback plan, customer impact, evidence links, and post-hoc review status.
A repository evidence index may be used for security reviews, but the operational register is the administrator-controlled system of record.
Roadmap
A rolling two-year product roadmap is maintained at hiringcoach.ai/roadmap.
Related
- secure development lifecycle: secure development practices
- patch management: dependency/CVE SLAs
- incident response: emergency-change post-mortems