universal-dev-standards 5.2.0 → 5.3.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/bundled/ai/options/release/publish-mode-github-actions.ai.yaml +65 -0
- package/bundled/ai/standards/cd-deployment-strategies.ai.yaml +73 -0
- package/bundled/ai/standards/no-cicd-deployment.ai.yaml +134 -0
- package/bundled/ai/standards/pipeline-security-gates.ai.yaml +71 -0
- package/bundled/ai/standards/push-standards.ai.yaml +105 -0
- package/bundled/ai/standards/rollback-standards.ai.yaml +68 -0
- package/bundled/core/cd-deployment-strategies.md +121 -0
- package/bundled/core/no-cicd-deployment.md +205 -0
- package/bundled/core/pipeline-security-gates.md +109 -0
- package/bundled/core/rollback-standards.md +104 -0
- package/bundled/locales/zh-CN/CHANGELOG.md +14 -3
- package/bundled/locales/zh-CN/README.md +48 -9
- package/bundled/locales/zh-TW/CHANGELOG.md +14 -3
- package/bundled/locales/zh-TW/README.md +47 -8
- package/bundled/locales/zh-TW/skills/deploy-assistant/SKILL.md +178 -0
- package/bundled/skills/deploy-assistant/SKILL.md +183 -0
- package/package.json +1 -1
- package/standards-registry.json +59 -3
|
@@ -0,0 +1,65 @@
|
|
|
1
|
+
# Release Option: GitHub Actions Publish Mode - AI Optimized
|
|
2
|
+
# Parent: release-standards
|
|
3
|
+
# Source: options/release/publish-mode-github-actions.md
|
|
4
|
+
|
|
5
|
+
id: publish-mode-github-actions
|
|
6
|
+
meta:
|
|
7
|
+
parent: release-standards
|
|
8
|
+
version: "1.0.0"
|
|
9
|
+
updated: "2026-04-24"
|
|
10
|
+
source: options/release/publish-mode-github-actions.md
|
|
11
|
+
description: CD publish pattern for npm packages — publish is triggered automatically by GitHub Release, not by manual `npm publish`
|
|
12
|
+
|
|
13
|
+
best_for:
|
|
14
|
+
- npm packages hosted in GitHub repositories
|
|
15
|
+
- Projects with GitHub Actions publish workflow (publish.yml or similar)
|
|
16
|
+
- Single-owner or small-team repos using GitHub Actions CD
|
|
17
|
+
- Projects where NPM_TOKEN is stored as a GitHub Actions secret
|
|
18
|
+
|
|
19
|
+
configuration:
|
|
20
|
+
publish_mode: github-actions
|
|
21
|
+
publish_trigger: gh_release_create
|
|
22
|
+
publish_command: none # npm publish is handled by GitHub Actions
|
|
23
|
+
tag_format: "v{semver}"
|
|
24
|
+
|
|
25
|
+
behaviors:
|
|
26
|
+
release_finish_sequence:
|
|
27
|
+
steps:
|
|
28
|
+
- bump_version # scripts/bump-version.sh or npm version
|
|
29
|
+
- update_changelog # add [X.Y.Z] section, remove from [Unreleased]
|
|
30
|
+
- commit_and_tag # git commit + git tag vX.Y.Z
|
|
31
|
+
- push_with_tag # git push origin main vX.Y.Z
|
|
32
|
+
- create_gh_release # gh release create vX.Y.Z --title "vX.Y.Z" --notes "..."
|
|
33
|
+
note: >
|
|
34
|
+
DO NOT run `npm publish` manually. The `gh release create` command triggers
|
|
35
|
+
the publish workflow via `release: published` event. GitHub Actions handles
|
|
36
|
+
the actual npm publish using NPM_TOKEN stored as a repository secret.
|
|
37
|
+
|
|
38
|
+
gh_release_create:
|
|
39
|
+
command: 'gh release create v{version} --title "v{version}" --notes "{changelog_entry}"'
|
|
40
|
+
triggers: publish_workflow
|
|
41
|
+
publishes_to_npm_tag:
|
|
42
|
+
stable: latest # versions without pre-release suffix (e.g. 5.2.0)
|
|
43
|
+
prerelease: next # versions with beta/alpha/rc suffix (e.g. 5.2.0-beta.1)
|
|
44
|
+
|
|
45
|
+
publish_workflow:
|
|
46
|
+
trigger_event: "release: published"
|
|
47
|
+
secret_required: NPM_TOKEN
|
|
48
|
+
runs_on: github_actions
|
|
49
|
+
note: >
|
|
50
|
+
Workflow file is typically `.github/workflows/publish.yml`.
|
|
51
|
+
It runs `npm publish` with `NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}`.
|
|
52
|
+
|
|
53
|
+
local_verification:
|
|
54
|
+
before_release:
|
|
55
|
+
- run_tests # npm test / vitest
|
|
56
|
+
- verify_build # npm run build (if applicable)
|
|
57
|
+
- check_version # confirm package.json version matches intended tag
|
|
58
|
+
note: All local gates must pass before `gh release create`
|
|
59
|
+
|
|
60
|
+
comparison_with_manual_mode:
|
|
61
|
+
publish_command: "not run locally" # manual: npm publish
|
|
62
|
+
publish_trigger: gh_release_create # manual: direct npm publish
|
|
63
|
+
npm_token_location: github_secret # manual: local .npmrc or env var
|
|
64
|
+
audit_trail: github_actions_log # manual: none (local terminal)
|
|
65
|
+
reproducibility: full_ci_isolation # manual: depends on local environment
|
|
@@ -0,0 +1,73 @@
|
|
|
1
|
+
# CD Deployment Strategies (AI-Optimized v1)
|
|
2
|
+
# Source: core/cd-deployment-strategies.md
|
|
3
|
+
|
|
4
|
+
standard:
|
|
5
|
+
id: cd-deployment-strategies
|
|
6
|
+
name: CD Deployment Strategies
|
|
7
|
+
description: Strategy selection matrix for blue-green, canary, rolling, and recreate deployments
|
|
8
|
+
guidelines:
|
|
9
|
+
- "Choose strategy based on: traffic volume × risk tolerance × infrastructure cost"
|
|
10
|
+
- "High traffic + low risk tolerance → blue-green (instant rollback)"
|
|
11
|
+
- "Medium traffic + medium risk → canary (progressive validation)"
|
|
12
|
+
- "Low traffic + low risk → rolling (resource efficient)"
|
|
13
|
+
- "Dev/internal only → recreate (simplest, acceptable downtime)"
|
|
14
|
+
- "Never deploy directly to production without staging validation"
|
|
15
|
+
|
|
16
|
+
meta:
|
|
17
|
+
version: "1.0.0"
|
|
18
|
+
updated: "2026-04-26"
|
|
19
|
+
source: core/cd-deployment-strategies.md
|
|
20
|
+
parent: deployment-standards.ai.yaml
|
|
21
|
+
|
|
22
|
+
strategy_matrix:
|
|
23
|
+
blue_green:
|
|
24
|
+
traffic: high
|
|
25
|
+
risk_tolerance: low
|
|
26
|
+
infrastructure_cost: high
|
|
27
|
+
downtime: zero
|
|
28
|
+
rollback_time: "<30s"
|
|
29
|
+
use_cases: ["stateful services", "database-compatible changes", "high-SLA APIs"]
|
|
30
|
+
prerequisites: ["dual environment", "load balancer", "health checks"]
|
|
31
|
+
canary:
|
|
32
|
+
traffic: medium_to_high
|
|
33
|
+
risk_tolerance: medium
|
|
34
|
+
infrastructure_cost: medium
|
|
35
|
+
downtime: zero
|
|
36
|
+
rollback_time: "<2min"
|
|
37
|
+
use_cases: ["feature validation", "A/B testing", "high-risk changes"]
|
|
38
|
+
traffic_stages: ["1%", "5%", "25%", "50%", "100%"]
|
|
39
|
+
prerequisites: ["traffic splitting", "observability", "auto-promotion rules"]
|
|
40
|
+
rolling:
|
|
41
|
+
traffic: any
|
|
42
|
+
risk_tolerance: medium
|
|
43
|
+
infrastructure_cost: low
|
|
44
|
+
downtime: minimal
|
|
45
|
+
rollback_time: "minutes"
|
|
46
|
+
use_cases: ["stateless services", "standard updates", "batch workers"]
|
|
47
|
+
prerequisites: ["multiple instances", "health checks"]
|
|
48
|
+
recreate:
|
|
49
|
+
traffic: low
|
|
50
|
+
risk_tolerance: high
|
|
51
|
+
infrastructure_cost: minimal
|
|
52
|
+
downtime: "seconds to minutes"
|
|
53
|
+
rollback_time: "minutes"
|
|
54
|
+
use_cases: ["dev/staging", "internal tools", "single-instance services"]
|
|
55
|
+
prerequisites: ["none"]
|
|
56
|
+
|
|
57
|
+
decision_tree:
|
|
58
|
+
step_1: "Is zero-downtime required? No → recreate; Yes → continue"
|
|
59
|
+
step_2: "Is traffic > 10k req/min? Yes → blue-green or canary; No → rolling"
|
|
60
|
+
step_3: "Is change high-risk? Yes → canary; No → blue-green or rolling"
|
|
61
|
+
step_4: "Is infrastructure budget constrained? Yes → rolling; No → blue-green"
|
|
62
|
+
|
|
63
|
+
no_cicd_compatibility:
|
|
64
|
+
blue_green: "See no-cicd-deployment.ai.yaml for script-based implementation"
|
|
65
|
+
canary: "Requires Nginx split_clients or HAProxy for script-based canary"
|
|
66
|
+
rolling: "Achievable with sequential rsync + health check loop"
|
|
67
|
+
recreate: "Simplest — stop, deploy, start"
|
|
68
|
+
|
|
69
|
+
physical_spec:
|
|
70
|
+
type: custom_script
|
|
71
|
+
validator:
|
|
72
|
+
command: "grep -r 'deployment_strategy\\|deploy.*strategy' . --include='*.yaml' --include='*.json' -l 2>/dev/null | head -1"
|
|
73
|
+
rule: "deployment_strategy_documented"
|
|
@@ -0,0 +1,134 @@
|
|
|
1
|
+
# No-CI/CD Deployment Strategy (AI-Optimized v1)
|
|
2
|
+
# Source: core/no-cicd-deployment.md
|
|
3
|
+
|
|
4
|
+
standard:
|
|
5
|
+
id: no-cicd-deployment
|
|
6
|
+
name: No-CI/CD Deployment Strategy
|
|
7
|
+
description: Reliable deployment without CI/CD platforms using shell scripts, smoke tests, Blue-Green switching, and deploy.lock protection
|
|
8
|
+
guidelines:
|
|
9
|
+
- "Use set -euo pipefail in all deploy scripts — fail fast, stop on first error"
|
|
10
|
+
- "Always verify deployment after completion — check version endpoint, never assume success"
|
|
11
|
+
- "Maintain Blue-Green slots for instant rollback — recovery time must be <30 seconds"
|
|
12
|
+
- "Enforce deploy.lock to prevent concurrent deployments"
|
|
13
|
+
- "Only deploy commits with semantic version tags — no untagged HEAD deployments"
|
|
14
|
+
- "Log every deployment with timestamp, version, operator, and result (JSON Lines)"
|
|
15
|
+
|
|
16
|
+
meta:
|
|
17
|
+
version: "1.0.0"
|
|
18
|
+
updated: "2026-04-26"
|
|
19
|
+
source: core/no-cicd-deployment.md
|
|
20
|
+
description: Reliable deployment strategy for environments without CI/CD platforms
|
|
21
|
+
complements: deployment-standards.ai.yaml
|
|
22
|
+
|
|
23
|
+
principles:
|
|
24
|
+
core:
|
|
25
|
+
- fail_fast: "set -euo pipefail stops execution at first failure — no silent partial deploys"
|
|
26
|
+
- verify_always: "Post-deploy smoke test is mandatory, not optional"
|
|
27
|
+
- instant_recovery: "Blue-Green rollback must complete in <30 seconds"
|
|
28
|
+
- concurrent_protection: "deploy.lock prevents race conditions from simultaneous deployments"
|
|
29
|
+
- version_discipline: "Only semver-tagged commits are deployable"
|
|
30
|
+
- audit_trail: "Every deploy produces a machine-readable log entry"
|
|
31
|
+
|
|
32
|
+
architecture:
|
|
33
|
+
three_layer:
|
|
34
|
+
layer_1_prevent:
|
|
35
|
+
name: "Prevent Wrong Deployments"
|
|
36
|
+
mechanisms:
|
|
37
|
+
- "set -euo pipefail in deploy.sh"
|
|
38
|
+
- "Mandatory test pass before deploy"
|
|
39
|
+
- "Semver tag enforcement"
|
|
40
|
+
- "deploy.lock concurrency guard"
|
|
41
|
+
layer_2_verify:
|
|
42
|
+
name: "Verify Deployment Correctness"
|
|
43
|
+
mechanisms:
|
|
44
|
+
- "HTTP /health endpoint check"
|
|
45
|
+
- "Version number comparison with VERSION file"
|
|
46
|
+
- "Auto-rollback on verification failure"
|
|
47
|
+
layer_3_recover:
|
|
48
|
+
name: "Fast Recovery Capability"
|
|
49
|
+
mechanisms:
|
|
50
|
+
- "Blue-Green slot switching"
|
|
51
|
+
- "Nginx upstream pointer swap"
|
|
52
|
+
- "Single-command rollback.sh"
|
|
53
|
+
|
|
54
|
+
deploy_script:
|
|
55
|
+
required_header: "#!/usr/bin/env bash\nset -euo pipefail"
|
|
56
|
+
mandatory_steps:
|
|
57
|
+
- step: test
|
|
58
|
+
order: 1
|
|
59
|
+
description: "Run full test suite before any deployment"
|
|
60
|
+
- step: build
|
|
61
|
+
order: 2
|
|
62
|
+
description: "Produce deployment artifact"
|
|
63
|
+
- step: deploy
|
|
64
|
+
order: 3
|
|
65
|
+
description: "Transfer artifact to target server"
|
|
66
|
+
- step: verify
|
|
67
|
+
order: 4
|
|
68
|
+
description: "Run smoke test; auto-rollback on failure"
|
|
69
|
+
lock_pattern:
|
|
70
|
+
file: "/tmp/deploy.lock"
|
|
71
|
+
create: "echo $$ > $LOCK_FILE"
|
|
72
|
+
cleanup: "trap 'rm -f $LOCK_FILE' EXIT"
|
|
73
|
+
check: "[ -f $LOCK_FILE ] && echo 'Deploy in progress' && exit 1"
|
|
74
|
+
version_enforcement:
|
|
75
|
+
command: "git describe --exact-match --tags HEAD"
|
|
76
|
+
format: "v[0-9]+\\.[0-9]+\\.[0-9]+"
|
|
77
|
+
failure_message: "No semver tag on HEAD — tag before deploying"
|
|
78
|
+
|
|
79
|
+
smoke_test:
|
|
80
|
+
endpoint: "/health"
|
|
81
|
+
required_fields:
|
|
82
|
+
- field: "version"
|
|
83
|
+
source: "VERSION file"
|
|
84
|
+
comparison: "exact match"
|
|
85
|
+
- field: "status"
|
|
86
|
+
expected: "ok"
|
|
87
|
+
failure_action: "auto_rollback"
|
|
88
|
+
timeout_seconds: 30
|
|
89
|
+
|
|
90
|
+
blue_green:
|
|
91
|
+
slots:
|
|
92
|
+
- name: blue
|
|
93
|
+
port: 3001
|
|
94
|
+
state: "active (stable)"
|
|
95
|
+
- name: green
|
|
96
|
+
port: 3002
|
|
97
|
+
state: "inactive (staging)"
|
|
98
|
+
switch_mechanism: "nginx upstream pointer"
|
|
99
|
+
rollback_time_sla: "30 seconds"
|
|
100
|
+
rollback_command: "./rollback.sh"
|
|
101
|
+
|
|
102
|
+
deployment_log:
|
|
103
|
+
format: "JSON Lines"
|
|
104
|
+
required_fields:
|
|
105
|
+
- "timestamp (ISO 8601)"
|
|
106
|
+
- "version"
|
|
107
|
+
- "git_commit"
|
|
108
|
+
- "operator (whoami)"
|
|
109
|
+
- "result (success|failure)"
|
|
110
|
+
- "duration_seconds"
|
|
111
|
+
location: "/var/log/deployments.jsonl"
|
|
112
|
+
|
|
113
|
+
checklist:
|
|
114
|
+
pre_deploy:
|
|
115
|
+
- "Tests pass"
|
|
116
|
+
- "Artifact built successfully"
|
|
117
|
+
- "No deploy.lock present"
|
|
118
|
+
- "HEAD has semver tag"
|
|
119
|
+
- "Previous deployment log reviewed"
|
|
120
|
+
post_deploy:
|
|
121
|
+
- "Health check HTTP 200"
|
|
122
|
+
- "Version matches expected"
|
|
123
|
+
- "Service responds to basic requests"
|
|
124
|
+
- "Deployment log entry written"
|
|
125
|
+
rollback_readiness:
|
|
126
|
+
- "Blue slot running previous stable version"
|
|
127
|
+
- "rollback.sh tested and functional"
|
|
128
|
+
- "Nginx upstream reload works"
|
|
129
|
+
|
|
130
|
+
physical_spec:
|
|
131
|
+
type: custom_script
|
|
132
|
+
validator:
|
|
133
|
+
command: "test -f deploy.sh && grep -q 'set -euo pipefail' deploy.sh && test -f rollback.sh && test -f verify.sh"
|
|
134
|
+
rule: "no_cicd_deployment_scripts_configured"
|
|
@@ -0,0 +1,71 @@
|
|
|
1
|
+
# Pipeline Security Gates (AI-Optimized v1)
|
|
2
|
+
# Source: core/pipeline-security-gates.md
|
|
3
|
+
|
|
4
|
+
standard:
|
|
5
|
+
id: pipeline-security-gates
|
|
6
|
+
name: Pipeline Security Gates
|
|
7
|
+
description: Security checkpoints embedded in CI pipeline — SAST, DAST, SCA, secrets scan with block/warn/log behavior
|
|
8
|
+
guidelines:
|
|
9
|
+
- "Secrets scan at pre-commit — block ALL commits containing secrets"
|
|
10
|
+
- "SAST after build — block Critical/High findings"
|
|
11
|
+
- "SCA + SBOM generation at package stage"
|
|
12
|
+
- "DAST after staging deploy — warn on findings, require approval for Critical"
|
|
13
|
+
- "Never skip security gates with --force or emergency bypass without audit trail"
|
|
14
|
+
- "Treat security gate failures as pipeline failures, not warnings"
|
|
15
|
+
|
|
16
|
+
meta:
|
|
17
|
+
version: "1.0.0"
|
|
18
|
+
updated: "2026-04-26"
|
|
19
|
+
source: core/pipeline-security-gates.md
|
|
20
|
+
complements: security-standards.ai.yaml
|
|
21
|
+
|
|
22
|
+
gate_positions:
|
|
23
|
+
pre_commit:
|
|
24
|
+
type: secrets_scan
|
|
25
|
+
tools: ["gitleaks", "trufflehog", "detect-secrets"]
|
|
26
|
+
scope: "staged files"
|
|
27
|
+
block_on: ["any secret pattern match"]
|
|
28
|
+
never_skip: true
|
|
29
|
+
post_build:
|
|
30
|
+
type: sast
|
|
31
|
+
tools: ["semgrep", "codeql", "sonarqube"]
|
|
32
|
+
scope: "source code + build output"
|
|
33
|
+
block_on: ["Critical", "High"]
|
|
34
|
+
warn_on: ["Medium"]
|
|
35
|
+
log_only: ["Low", "Info"]
|
|
36
|
+
post_staging_deploy:
|
|
37
|
+
type: dast
|
|
38
|
+
tools: ["zap", "nuclei", "burpsuite-enterprise"]
|
|
39
|
+
scope: "running staging application"
|
|
40
|
+
block_on: ["Critical"]
|
|
41
|
+
require_approval: ["High"]
|
|
42
|
+
warn_on: ["Medium"]
|
|
43
|
+
package_stage:
|
|
44
|
+
type: sca_and_sbom
|
|
45
|
+
tools: ["trivy", "syft", "grype", "dependabot"]
|
|
46
|
+
scope: "dependencies + container image"
|
|
47
|
+
block_on: ["Critical CVE with fix available"]
|
|
48
|
+
warn_on: ["High CVE", "outdated dependencies"]
|
|
49
|
+
sbom_format: ["spdx", "cyclonedx"]
|
|
50
|
+
|
|
51
|
+
bypass_policy:
|
|
52
|
+
allowed: false
|
|
53
|
+
exception_process: "written security approval + audit log entry"
|
|
54
|
+
emergency_bypass: "time-limited token + mandatory post-incident review"
|
|
55
|
+
|
|
56
|
+
failure_behavior:
|
|
57
|
+
Critical: {action: "block pipeline", notify: "security-team", sla: "immediate"}
|
|
58
|
+
High: {action: "block pipeline", notify: "team-lead", sla: "same-day"}
|
|
59
|
+
Medium: {action: "warn + require approval", notify: "developer", sla: "next-sprint"}
|
|
60
|
+
Low: {action: "log only", notify: "none", sla: "backlog"}
|
|
61
|
+
|
|
62
|
+
integration_points:
|
|
63
|
+
secrets_vault: "Integrate with HashiCorp Vault or AWS Secrets Manager for secrets injection"
|
|
64
|
+
sbom_registry: "Upload SBOM to dependency-track or grype-db for continuous monitoring"
|
|
65
|
+
incident_response: "Critical findings automatically create incident tickets"
|
|
66
|
+
|
|
67
|
+
physical_spec:
|
|
68
|
+
type: custom_script
|
|
69
|
+
validator:
|
|
70
|
+
command: "grep -r 'secrets\\|sast\\|sca\\|dast' .github/workflows/ .gitlab-ci.yml Jenkinsfile 2>/dev/null | head -1 || echo 'no-ci-pipeline'"
|
|
71
|
+
rule: "security_gates_in_pipeline"
|
|
@@ -0,0 +1,105 @@
|
|
|
1
|
+
id: push-standards
|
|
2
|
+
meta:
|
|
3
|
+
version: "1.0.0"
|
|
4
|
+
updated: "2026-04-23"
|
|
5
|
+
source: skills/push/SKILL.md
|
|
6
|
+
description: "Git push safety gates, protected branch detection, force-push guardrails, and push receipt audit trail"
|
|
7
|
+
|
|
8
|
+
config:
|
|
9
|
+
protected_branches:
|
|
10
|
+
default: ["main", "master", "release/*", "hotfix/*"]
|
|
11
|
+
description: "Branches requiring explicit confirmation before push"
|
|
12
|
+
|
|
13
|
+
push_gates:
|
|
14
|
+
default: ["lint", "test"]
|
|
15
|
+
optional: ["ac-coverage", "type-check", "security-scan"]
|
|
16
|
+
description: "Quality gates to run before pushing"
|
|
17
|
+
|
|
18
|
+
receipt:
|
|
19
|
+
output:
|
|
20
|
+
default: "console"
|
|
21
|
+
choices: ["console", "file", "both"]
|
|
22
|
+
file_path: "~/.uds/push-history.jsonl"
|
|
23
|
+
|
|
24
|
+
auto_pr:
|
|
25
|
+
default: true
|
|
26
|
+
description: "Prompt to create PR after pushing to non-protected branch"
|
|
27
|
+
|
|
28
|
+
repo_mode:
|
|
29
|
+
default: "team"
|
|
30
|
+
choices: ["team", "single-owner"]
|
|
31
|
+
description: "single-owner skips PR prompts and reduces collaboration guardrails"
|
|
32
|
+
|
|
33
|
+
rules:
|
|
34
|
+
- id: detect-protected-branch
|
|
35
|
+
trigger: "executing /push"
|
|
36
|
+
priority: required
|
|
37
|
+
instruction: |
|
|
38
|
+
Before pushing, detect the target branch name.
|
|
39
|
+
If the target matches any protected_branches pattern:
|
|
40
|
+
1. Display a warning with the branch name
|
|
41
|
+
2. Show what commits will be pushed
|
|
42
|
+
3. Require explicit user confirmation before proceeding
|
|
43
|
+
4. If user does not confirm, abort without pushing
|
|
44
|
+
|
|
45
|
+
- id: force-push-guardrail
|
|
46
|
+
trigger: "push with --force flag detected"
|
|
47
|
+
priority: required
|
|
48
|
+
instruction: |
|
|
49
|
+
When force push is detected:
|
|
50
|
+
1. Calculate commits that will be overwritten on remote
|
|
51
|
+
2. Show the count and authors of overwritten commits
|
|
52
|
+
3. Require the user to type a confirmation string (e.g., "yes, force push")
|
|
53
|
+
4. Record force_push: true in the push receipt
|
|
54
|
+
|
|
55
|
+
- id: pre-push-gates
|
|
56
|
+
trigger: "before executing git push"
|
|
57
|
+
priority: required
|
|
58
|
+
instruction: |
|
|
59
|
+
Run all configured push_gates in sequence:
|
|
60
|
+
- lint: run project lint command (from uds.project.yaml or detected)
|
|
61
|
+
- test: run project test command
|
|
62
|
+
If any gate fails: abort push, display which gate failed, suggest fix.
|
|
63
|
+
If --skip-gates flag: run push without gates, mark gates_skipped: true in receipt.
|
|
64
|
+
|
|
65
|
+
- id: push-receipt
|
|
66
|
+
trigger: "after successful push"
|
|
67
|
+
priority: required
|
|
68
|
+
instruction: |
|
|
69
|
+
Output a structured push receipt containing:
|
|
70
|
+
- branch: target branch name
|
|
71
|
+
- commit_sha: HEAD commit SHA (short)
|
|
72
|
+
- gates_passed: list of gates that ran and passed
|
|
73
|
+
- gates_skipped: boolean
|
|
74
|
+
- force_push: boolean
|
|
75
|
+
- timestamp: ISO 8601 format
|
|
76
|
+
If receipt.output includes "file": append to ~/.uds/push-history.jsonl as JSON line.
|
|
77
|
+
|
|
78
|
+
- id: pr-integration
|
|
79
|
+
trigger: "after successful push to non-protected branch"
|
|
80
|
+
priority: suggested
|
|
81
|
+
instruction: |
|
|
82
|
+
If auto_pr is true AND repo_mode is "team":
|
|
83
|
+
Check if an open PR exists for this branch on the remote.
|
|
84
|
+
If no open PR: prompt user whether to run pr-automation-assistant.
|
|
85
|
+
If user confirms: invoke pr-automation-assistant.
|
|
86
|
+
If auto_pr is false OR repo_mode is "single-owner": skip this step.
|
|
87
|
+
|
|
88
|
+
- id: single-owner-mode
|
|
89
|
+
trigger: "repo_mode: single-owner is configured"
|
|
90
|
+
priority: recommended
|
|
91
|
+
instruction: |
|
|
92
|
+
In single-owner mode, skip all collaboration-specific steps:
|
|
93
|
+
- No PR prompts
|
|
94
|
+
- Reduced force-push warnings (still warn, but no confirmation text required)
|
|
95
|
+
Protected branch detection remains active.
|
|
96
|
+
|
|
97
|
+
schema:
|
|
98
|
+
push_receipt:
|
|
99
|
+
branch: string
|
|
100
|
+
commit_sha: string
|
|
101
|
+
gates_passed: "string[]"
|
|
102
|
+
gates_skipped: boolean
|
|
103
|
+
force_push: boolean
|
|
104
|
+
timestamp: "ISO 8601 string"
|
|
105
|
+
target_remote: string
|
|
@@ -0,0 +1,68 @@
|
|
|
1
|
+
# Rollback Standards (AI-Optimized v1)
|
|
2
|
+
# Source: core/rollback-standards.md
|
|
3
|
+
|
|
4
|
+
standard:
|
|
5
|
+
id: rollback-standards
|
|
6
|
+
name: Rollback Standards
|
|
7
|
+
description: Rollback trigger conditions, auto vs manual decisions, and error budget integration
|
|
8
|
+
guidelines:
|
|
9
|
+
- "Define rollback triggers with measurable thresholds — never subjective 'it looks bad'"
|
|
10
|
+
- "Auto-rollback on error rate > 2× baseline sustained 5 minutes"
|
|
11
|
+
- "Assisted rollback when SLO violated but non-critical"
|
|
12
|
+
- "Manual rollback for latency degradation within SLO bounds"
|
|
13
|
+
- "Error budget < 10% automatically escalates assisted to auto-rollback"
|
|
14
|
+
- "Every rollback event must be logged and trigger incident response flow"
|
|
15
|
+
|
|
16
|
+
meta:
|
|
17
|
+
version: "1.0.0"
|
|
18
|
+
updated: "2026-04-26"
|
|
19
|
+
source: core/rollback-standards.md
|
|
20
|
+
parent: deployment-standards.ai.yaml
|
|
21
|
+
|
|
22
|
+
trigger_conditions:
|
|
23
|
+
auto_rollback:
|
|
24
|
+
error_rate: ">2× baseline sustained 5min"
|
|
25
|
+
health_check_failures: "3 consecutive"
|
|
26
|
+
p99_latency: ">5× baseline sustained 3min"
|
|
27
|
+
assisted_rollback:
|
|
28
|
+
slo_violated: "non-critical path"
|
|
29
|
+
error_budget_remaining: "<10%"
|
|
30
|
+
manual_rollback:
|
|
31
|
+
latency_degraded: "within SLO bounds"
|
|
32
|
+
cosmetic_issues: "user-visible but non-functional"
|
|
33
|
+
|
|
34
|
+
severity_matrix:
|
|
35
|
+
P0: {trigger: auto, timeline: "<2min", notify: "all-hands"}
|
|
36
|
+
P1: {trigger: auto, timeline: "<5min", notify: "on-call"}
|
|
37
|
+
P2: {trigger: assisted, timeline: "<15min", notify: "team-lead"}
|
|
38
|
+
P3: {trigger: manual, timeline: "<1hr", notify: "developer"}
|
|
39
|
+
|
|
40
|
+
error_budget_integration:
|
|
41
|
+
threshold: "10% remaining"
|
|
42
|
+
escalation: "assisted → auto"
|
|
43
|
+
incident_event: true
|
|
44
|
+
pause_deploys: "when budget exhausted"
|
|
45
|
+
|
|
46
|
+
rollback_methods:
|
|
47
|
+
blue_green: {time: "<30s", risk: low, prerequisite: "dual-slot infrastructure"}
|
|
48
|
+
feature_flag: {time: "<5s", risk: minimal, prerequisite: "flag system in place"}
|
|
49
|
+
dns_switch: {time: "60-120s", risk: medium, prerequisite: "multi-region setup"}
|
|
50
|
+
code_revert: {time: "minutes", risk: medium, prerequisite: "clean git history"}
|
|
51
|
+
database_restore: {time: "hours", risk: high, prerequisite: "backup verified"}
|
|
52
|
+
|
|
53
|
+
checklist:
|
|
54
|
+
pre_rollback:
|
|
55
|
+
- "Confirm rollback target version is healthy"
|
|
56
|
+
- "Verify database migration is backward compatible"
|
|
57
|
+
- "Notify stakeholders of rollback"
|
|
58
|
+
post_rollback:
|
|
59
|
+
- "Confirm health checks pass at target version"
|
|
60
|
+
- "Write rollback event to deployment log"
|
|
61
|
+
- "Open incident ticket for root cause analysis"
|
|
62
|
+
- "Update error budget tracking"
|
|
63
|
+
|
|
64
|
+
physical_spec:
|
|
65
|
+
type: custom_script
|
|
66
|
+
validator:
|
|
67
|
+
command: "test -f rollback.sh && grep -q 'set -euo pipefail' rollback.sh"
|
|
68
|
+
rule: "rollback_script_configured"
|
|
@@ -0,0 +1,121 @@
|
|
|
1
|
+
# CD Deployment Strategies(CD 部署策略)
|
|
2
|
+
|
|
3
|
+
## 概述
|
|
4
|
+
|
|
5
|
+
本標準定義四種主要部署策略的選用矩陣:Blue-Green、Canary、Rolling、Recreate。幫助團隊根據流量規模、風險容忍度和基礎設施成本,做出一致且有據可查的策略選擇。
|
|
6
|
+
|
|
7
|
+
---
|
|
8
|
+
|
|
9
|
+
## 核心原則
|
|
10
|
+
|
|
11
|
+
- **三維決策**:根據流量規模 × 風險容忍度 × 基礎設施成本選擇策略
|
|
12
|
+
- **禁止直接推產**:任何變更都必須先通過 staging 環境驗證
|
|
13
|
+
- **零停機目標**:除非為內部工具或開發環境,否則應追求零停機部署
|
|
14
|
+
|
|
15
|
+
---
|
|
16
|
+
|
|
17
|
+
## 策略選用矩陣
|
|
18
|
+
|
|
19
|
+
| 策略 | 流量規模 | 風險容忍度 | 基礎設施成本 | 停機時間 | 回滾時間 |
|
|
20
|
+
|------|---------|----------|------------|---------|---------|
|
|
21
|
+
| Blue-Green | 高 | 低 | 高 | 零 | < 30 秒 |
|
|
22
|
+
| Canary | 中至高 | 中 | 中 | 零 | < 2 分鐘 |
|
|
23
|
+
| Rolling | 任意 | 中 | 低 | 極少 | 數分鐘 |
|
|
24
|
+
| Recreate | 低 | 高 | 極低 | 數秒至數分鐘 | 數分鐘 |
|
|
25
|
+
|
|
26
|
+
---
|
|
27
|
+
|
|
28
|
+
## 各策略詳細說明
|
|
29
|
+
|
|
30
|
+
### Blue-Green
|
|
31
|
+
|
|
32
|
+
**適用場景**:有狀態服務、資料庫相容性變更、高 SLA API
|
|
33
|
+
|
|
34
|
+
**運作方式**:
|
|
35
|
+
- 維護兩個完全相同的環境(Blue = 現有線上版,Green = 新版本)
|
|
36
|
+
- 完整部署並驗證 Green 環境後,切換 Load Balancer 流量
|
|
37
|
+
- 問題發生時立即切回 Blue
|
|
38
|
+
|
|
39
|
+
**前置條件**:雙環境基礎設施、Load Balancer、健康檢查
|
|
40
|
+
|
|
41
|
+
---
|
|
42
|
+
|
|
43
|
+
### Canary
|
|
44
|
+
|
|
45
|
+
**適用場景**:功能驗證、A/B 測試、高風險變更
|
|
46
|
+
|
|
47
|
+
**流量漸進比例**:1% → 5% → 25% → 50% → 100%
|
|
48
|
+
|
|
49
|
+
**運作方式**:
|
|
50
|
+
- 先將少量流量導向新版本
|
|
51
|
+
- 監控指標,符合自動晉升規則則繼續擴大
|
|
52
|
+
- 發現問題立即縮回 0%
|
|
53
|
+
|
|
54
|
+
**前置條件**:流量切分機制、可觀測性、自動晉升規則
|
|
55
|
+
|
|
56
|
+
---
|
|
57
|
+
|
|
58
|
+
### Rolling
|
|
59
|
+
|
|
60
|
+
**適用場景**:無狀態服務、標準更新、批次工作者
|
|
61
|
+
|
|
62
|
+
**運作方式**:
|
|
63
|
+
- 依序更新每個實例,更新前進行健康檢查
|
|
64
|
+
- 允許新舊版本短暫共存
|
|
65
|
+
- 資源效率最佳,但回滾需時較長
|
|
66
|
+
|
|
67
|
+
**前置條件**:多個服務實例、健康檢查
|
|
68
|
+
|
|
69
|
+
---
|
|
70
|
+
|
|
71
|
+
### Recreate
|
|
72
|
+
|
|
73
|
+
**適用場景**:開發/測試環境、內部工具、單一實例服務
|
|
74
|
+
|
|
75
|
+
**運作方式**:
|
|
76
|
+
- 停止所有現有實例,部署新版本,重新啟動
|
|
77
|
+
- 最簡單,但有停機時間
|
|
78
|
+
|
|
79
|
+
**前置條件**:無(最低門檻)
|
|
80
|
+
|
|
81
|
+
---
|
|
82
|
+
|
|
83
|
+
## 決策樹
|
|
84
|
+
|
|
85
|
+
```
|
|
86
|
+
Q1: 需要零停機時間?
|
|
87
|
+
→ 否 → Recreate
|
|
88
|
+
→ 是 → Q2
|
|
89
|
+
|
|
90
|
+
Q2: 流量 > 10k req/min?
|
|
91
|
+
→ 是 → Q3(Blue-Green 或 Canary)
|
|
92
|
+
→ 否 → Rolling
|
|
93
|
+
|
|
94
|
+
Q3: 變更屬於高風險?
|
|
95
|
+
→ 是 → Canary
|
|
96
|
+
→ 否 → Q4
|
|
97
|
+
|
|
98
|
+
Q4: 基礎設施預算有限?
|
|
99
|
+
→ 是 → Rolling
|
|
100
|
+
→ 否 → Blue-Green
|
|
101
|
+
```
|
|
102
|
+
|
|
103
|
+
---
|
|
104
|
+
|
|
105
|
+
## 無 CI/CD 環境的替代做法
|
|
106
|
+
|
|
107
|
+
| 策略 | 替代方案 |
|
|
108
|
+
|------|---------|
|
|
109
|
+
| Blue-Green | 參見 no-cicd-deployment.ai.yaml 的 Shell Script 實作 |
|
|
110
|
+
| Canary | 使用 Nginx `split_clients` 或 HAProxy 做流量切分 |
|
|
111
|
+
| Rolling | 使用順序式 rsync + 健康檢查迴圈 |
|
|
112
|
+
| Recreate | 最簡單 — 停止、部署、啟動 |
|
|
113
|
+
|
|
114
|
+
---
|
|
115
|
+
|
|
116
|
+
## 相關標準
|
|
117
|
+
|
|
118
|
+
- [deployment-standards.md](deployment-standards.md) — 部署基礎原則
|
|
119
|
+
- [rollback-standards.md](rollback-standards.md) — 回滾觸發條件矩陣
|
|
120
|
+
- [no-cicd-deployment.md](no-cicd-deployment.md) — 無 CI/CD 部署策略
|
|
121
|
+
- AI 格式:[../ai/standards/cd-deployment-strategies.ai.yaml](../ai/standards/cd-deployment-strategies.ai.yaml)
|