shipping-and-launch

Name: shipping-and-launch
Author: jmxt3

32stars3forks

How to install shipping-and-launch?

jmxt3/gitscape.ai/shipping-and-launch

$npx -y skills add jmxt3/gitscape.ai --skill shipping-and-launch

Installs into the current project.

Summary

Prepares production launches. Use when preparing to deploy to production. Use when you need a pre-launch checklist, when setting up monitoring, when planning a staged rollout, or when you need a rollback strategy.

Files · 1

View on GitHub

SKILL.md

1	# Shipping and Launch
2
3	## Overview
4
5	Every production deploy is a risk management exercise. Move fast by being deliberate: know what you're deploying, have a rollback plan, verify the system is healthy after deploy, and keep the blast radius small. The fastest way to ship is to have a clean rollback when things go wrong — not to avoid deploying.
6
7	## When to Use
8
9	- Before any deployment to the Cloud Run production environment
10	- When deploying a feature that changes user-facing behavior
11	- When updating environment variables or secrets in GCP
12	- When rolling out a new API endpoint or removing an old one
13
14	## Pre-Deploy Checklist
15
16	Run this before triggering any Cloud Build deploy:
17
18	### Code Quality
19	- [ ] All tests pass locally: `pytest tests/ -v`
20	- [ ] No linting errors: `ruff check api/`
21	- [ ] TypeScript compiles: `npx tsc --noEmit` (in `web/`)
22	- [ ] No `TODO: before deploy` comments remaining
23
24	### Security
25	- [ ] No secrets committed to git: `git log --oneline -5` — check commit messages
26	- [ ] New environment variables are in GCP Secret Manager, not in `cloudbuild.yaml` as plaintext
27	- [ ] `.env.example` updated if new variables are required
28
29	### Observability
30	- [ ] New endpoints have structured logging (start/complete/error)
31	- [ ] New endpoints log request_id for correlation
32
33	### Documentation
34	- [ ] `README.md` updated if user-visible behavior changed
35	- [ ] New environment variables documented in `.env.example`
36	- [ ] ADR created if an architectural decision was made
37
38	### Rollback Readiness
39	- [ ] Know the previous working Cloud Run revision: `gcloud run revisions list`
40	- [ ] Know the rollback command (see below)
41
42	## Rollback Procedure
43
44	GitScape deploys to Cloud Run. Rolling back is instant:
45
46	```bash
47	# List revisions (most recent first)
48	gcloud run revisions list \
49	--service=gitscape-api \
50	--region=us-central1 \
51	--format="table(name,status.conditions[0].status,spec.containerConcurrency,metadata.creationTimestamp)"
52
53	# Rollback: send 100% traffic to the previous revision
54	gcloud run services update-traffic gitscape-api \
55	--to-revisions=PREVIOUS_REVISION_NAME=100 \
56	--region=us-central1
57	```
58
59	When to roll back:
60	- Error rate rises above 1% after deploy
61	- p95 latency exceeds 5 seconds
62	- Any Critical or High security finding is confirmed in production
63	- User-reported regressions in core functionality
64
65	## Feature Flag Lifecycle
66
67	For high-risk features, deploy behind a feature flag:
68
69	```python
70	# 1. Deploy with flag disabled (safe default)
71	FF_SKILL_HD_TIER = os.getenv("FF_SKILL_HD_TIER", "false").lower() == "true"
72
73	# 2. Enable in Cloud Run after confirming deploy is healthy
74	# gcloud run services update gitscape-api \
75	# --update-env-vars FF_SKILL_HD_TIER=true \
76	# --region=us-central1
77
78	# 3. Monitor for 30 minutes post-enable
79	# 4. Remove the flag once stable (no surprises for 7+ days)
80	```
81
82	Flag cleanup: Remove the flag code (and the env var) once the feature has been stable for at least 7 days.
83
84	## Staged Rollout
85
86	For high-confidence changes, deploy to all traffic immediately. For risky changes, use Cloud Run traffic splitting:
87
88	```bash
89	# Send 10% of traffic to new revision
90	gcloud run services update-traffic gitscape-api \
91	--to-revisions=NEW_REVISION=10,CURRENT_REVISION=90 \
92	--region=us-central1
93
94	# Promote to 100% after monitoring
95	gcloud run services update-traffic gitscape-api \
96	--to-latest \
97	--region=us-central1
98	```
99
100	## Post-Deploy Verification
101
102	After every deploy, verify within 10 minutes:
103
104	```bash
105	# 1. Check that the new revision is serving
106	gcloud run revisions describe $(gcloud run revisions list \
107	--service=gitscape-api --region=us-central1 \
108	--format="value(name)" --limit=1) \
109	--region=us-central1
110
111	# 2. Health check
112	curl https://api.gitscape.app/health
113
114	# 3. Smoke test: verify core functionality
115	curl -X POST https://api.gitscape.app/api/skills \
116	-H "Content-Type: application/json" \
117	-d '{"repo": "addyosmani/agent-skills"}'
118
119	# 4. Check Cloud Logging for errors
120	gcloud logging read \
121	'resource.type="cloud_run_revision" AND severity>=ERROR' \
122	--freshness=10m \
123	--limit=20
124	```
125
126	Green signals:
127	- Health check returns 200
128	- Smoke test returns a skill bundle
129	- No ERROR-level log lines in the 10 minutes post-deploy
130
131	Red signals (trigger rollback immediately):
132	- Health check fails
133	- Smoke test returns 5xx
134	- Error rate visible in Cloud Logging
135
136	## Common Rationalizations
137
138	\| Rationalization \| Reality \|
139	\|---\|---\|
140	\| "I'll skip the checklist this once — it's a small change" \| The small change you skip the checklist for is the one that goes wrong. \|
141	\| "I don't need a rollback plan — I'm confident in the change" \| Confidence is not a rollback plan. \|
142	\| "We can fix it forward if something goes wrong" \| Fixing forward takes longer tha

People who liked this also viewed

6 picks

Type

shipping-and-launch

32stars3forks

View on GitHub

How to install shipping-and-launch?

jmxt3/gitscape.ai/shipping-and-launch

$npx -y skills add jmxt3/gitscape.ai --skill shipping-and-launch

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	# Shipping and Launch
2
3	## Overview
4
5	Every production deploy is a risk management exercise. Move fast by being deliberate: know what you're deploying, have a rollback plan, verify the system is healthy after deploy, and keep the blast radius small. The fastest way to ship is to have a clean rollback when things go wrong — not to avoid deploying.
6
7	## When to Use
8
9	- Before any deployment to the Cloud Run production environment
10	- When deploying a feature that changes user-facing behavior
11	- When updating environment variables or secrets in GCP
12	- When rolling out a new API endpoint or removing an old one
13
14	## Pre-Deploy Checklist
15
16	Run this before triggering any Cloud Build deploy:
17
18	### Code Quality
19	- [ ] All tests pass locally: `pytest tests/ -v`
20	- [ ] No linting errors: `ruff check api/`
21	- [ ] TypeScript compiles: `npx tsc --noEmit` (in `web/`)
22	- [ ] No `TODO: before deploy` comments remaining
23
24	### Security
25	- [ ] No secrets committed to git: `git log --oneline -5` — check commit messages
26	- [ ] New environment variables are in GCP Secret Manager, not in `cloudbuild.yaml` as plaintext
27	- [ ] `.env.example` updated if new variables are required
28
29	### Observability
30	- [ ] New endpoints have structured logging (start/complete/error)
31	- [ ] New endpoints log request_id for correlation
32
33	### Documentation
34	- [ ] `README.md` updated if user-visible behavior changed
35	- [ ] New environment variables documented in `.env.example`
36	- [ ] ADR created if an architectural decision was made
37
38	### Rollback Readiness
39	- [ ] Know the previous working Cloud Run revision: `gcloud run revisions list`
40	- [ ] Know the rollback command (see below)
41
42	## Rollback Procedure
43
44	GitScape deploys to Cloud Run. Rolling back is instant:
45
46	```bash
47	# List revisions (most recent first)
48	gcloud run revisions list \
49	--service=gitscape-api \
50	--region=us-central1 \
51	--format="table(name,status.conditions[0].status,spec.containerConcurrency,metadata.creationTimestamp)"
52
53	# Rollback: send 100% traffic to the previous revision
54	gcloud run services update-traffic gitscape-api \
55	--to-revisions=PREVIOUS_REVISION_NAME=100 \
56	--region=us-central1
57	```
58
59	When to roll back:
60	- Error rate rises above 1% after deploy
61	- p95 latency exceeds 5 seconds
62	- Any Critical or High security finding is confirmed in production
63	- User-reported regressions in core functionality
64
65	## Feature Flag Lifecycle
66
67	For high-risk features, deploy behind a feature flag:
68
69	```python
70	# 1. Deploy with flag disabled (safe default)
71	FF_SKILL_HD_TIER = os.getenv("FF_SKILL_HD_TIER", "false").lower() == "true"
72
73	# 2. Enable in Cloud Run after confirming deploy is healthy
74	# gcloud run services update gitscape-api \
75	# --update-env-vars FF_SKILL_HD_TIER=true \
76	# --region=us-central1
77
78	# 3. Monitor for 30 minutes post-enable
79	# 4. Remove the flag once stable (no surprises for 7+ days)
80	```
81
82	Flag cleanup: Remove the flag code (and the env var) once the feature has been stable for at least 7 days.
83
84	## Staged Rollout
85
86	For high-confidence changes, deploy to all traffic immediately. For risky changes, use Cloud Run traffic splitting:
87
88	```bash
89	# Send 10% of traffic to new revision
90	gcloud run services update-traffic gitscape-api \
91	--to-revisions=NEW_REVISION=10,CURRENT_REVISION=90 \
92	--region=us-central1
93
94	# Promote to 100% after monitoring
95	gcloud run services update-traffic gitscape-api \
96	--to-latest \
97	--region=us-central1
98	```
99
100	## Post-Deploy Verification
101
102	After every deploy, verify within 10 minutes:
103
104	```bash
105	# 1. Check that the new revision is serving
106	gcloud run revisions describe $(gcloud run revisions list \
107	--service=gitscape-api --region=us-central1 \
108	--format="value(name)" --limit=1) \
109	--region=us-central1
110
111	# 2. Health check
112	curl https://api.gitscape.app/health
113
114	# 3. Smoke test: verify core functionality
115	curl -X POST https://api.gitscape.app/api/skills \
116	-H "Content-Type: application/json" \
117	-d '{"repo": "addyosmani/agent-skills"}'
118
119	# 4. Check Cloud Logging for errors
120	gcloud logging read \
121	'resource.type="cloud_run_revision" AND severity>=ERROR' \
122	--freshness=10m \
123	--limit=20
124	```
125
126	Green signals:
127	- Health check returns 200
128	- Smoke test returns a skill bundle
129	- No ERROR-level log lines in the 10 minutes post-deploy
130
131	Red signals (trigger rollback immediately):
132	- Health check fails
133	- Smoke test returns 5xx
134	- Error rate visible in Cloud Logging
135
136	## Common Rationalizations
137
138	\| Rationalization \| Reality \|
139	\|---\|---\|
140	\| "I'll skip the checklist this once — it's a small change" \| The small change you skip the checklist for is the one that goes wrong. \|
141	\| "I don't need a rollback plan — I'm confident in the change" \| Confidence is not a rollback plan. \|
142	\| "We can fix it forward if something goes wrong" \| Fixing forward takes longer tha

People who liked this also viewed

6 picks

Type