Internal communication for system updates

Deployment Communication Procedure

This procedure defines how Theora engineering communicates code-change deployments to the small (~5-10) remote team. It applies to every push that triggers cloudbuild.yaml at the repo root and results in a Cloud Run revision in project tactile-stack-491017-c0 (region us-central1). It complements the existing SOC 2 documentation in docs/soc2/ (see inventory-of-resources.md and risk-register.md).

1. Primary channel

The primary, system-of-record channel for deploy communication is the Slack channel #deploys in the Theora workspace. Slack is preferred over an email alias because:

• It supports threaded acknowledgements and emoji reactions for the operator acknowledgement flow.
• Slack search produces clean screenshots that satisfy the Vanta evidence request.
• Existing on-call discussion already happens in Slack.

A backup alias engineering@theora receives the same payload by email when Slack is unavailable (Slack incident, after-hours fallback). Channel membership is restricted to engineering personnel listed in docs/soc2/inventory-of-resources.md. Read-only auditor access may be granted in single-channel-guest mode during the audit window.

2. Required fields per deploy message

Every message posted by the CI bot or a human operator MUST include the following fields. Missing fields are treated as a procedure violation and tracked in the risk register.

Field	Example	Source
Commit SHA (short)	446d9e8	$SHORT_SHA in Cloud Build
Change summary	"retention: auto-delete expired user query data"	git commit subject
Environment	prod or staging	Cloud Build trigger name
Deploy time (UTC)	2026-06-01T14:22:07Z	Cloud Build finishTime
Operator	jagan@theora or cloudbuild-bot	Cloud Build substitutions._USER or trigger principal
Status / outcome	SUCCESS, FAILED, ROLLED-BACK	Cloud Build build status
Cloud Build run link	https://console.cloud.google.com/cloud-build/builds/?project=tactile-stack-491017-c0	Cloud Build
Cloud Run revision	theora-web-00142-abc	gcloud run services describe

3. Cadence

• Every production deploy posts exactly one message, posted within 60 seconds of Cloud Build completion.
• Every staging deploy posts a message (lower priority, no @here ping).
• Every rollback (gcloud run services update-traffic --to-revisions) posts a rollback notice tagged ROLLED-BACK with a link to the prior revision and an incident ticket reference.
• Failed builds also post (status FAILED) so the absence of a success message is never silently ignored.

4. Confirmation flow

Posting is automated where possible to remove human error:

1. A final step is added to cloudbuild.yaml that invokes the Slack incoming webhook stored in Secret Manager (SLACK_DEPLOY_WEBHOOK_URL) and posts the structured payload above. The webhook URL is mounted into the build step as an env var; least-privilege IAM (already in place per the platform's existing controls) restricts the secret to the Cloud Build service account.
2. On SUCCESS, the bot adds a green check reaction.
3. If the deploy was initiated manually (e.g. a one-off gcloud run deploy bypassing CI), the human operator MUST post the same payload manually and reply in-thread with the words "acknowledged by " within 15 minutes. This closes the gap when CI is bypassed.
4. Rollbacks always require a human in-thread reply naming the on-call engineer and linking the incident.

5. Retention

Slack message history in #deploys is retained for a minimum of 12 months. Theora's Slack workspace retention is configured at the channel level to "retain all messages" and is reviewed annually. For belt-and-suspenders durability and to align with the auto-deletion model used for user query data (see commit 50a8675 and docs/soc2/risk-register.md), a copy of every CI bot post is also written to Cloud Logging under log name deploy-announcements and retained for 400 days, which exceeds the 12-month requirement.

6. Relationship to existing Theora controls

• Cloud Logging entries are subject to core.logging.RedactingFilter; deploy payloads contain no user PII so redaction is a no-op but the path is consistent.
• The Slack webhook secret is stored in GCP Secret Manager and follows the same least-privilege IAM model documented in docs/soc2/inventory-of-resources.md.
• Vendor (Slack) is enumerated in docs/soc2/vendor-list.md; if Slack is not yet listed it MUST be added before the audit window closes.

7. Recent production change deployments

Theora's system of record for production code-change communication is the GitHub merge queue on the main branch of the production source repository. Every merge commit corresponds to a reviewed Pull Request whose title is the change summary, whose author is the operator of record, and whose timestamp is when the change went to production via Cloud Build → Cloud Run.

#	Merge SHA	Deploy time (local)	Operator	Change summary
1	f50488d	2026-06-02 19:53	JAGANNATH N	PR #2 — fix(trust): address Vanta reviewer feedback on submitted SOC 2 docs
2	7f73cfb	2026-06-01 19:03	JAGANNATH N	PR #1 — feat(trust): public Trust Center + SOC 2 Engineering evidence section
3	446d9e8	2026-05-13 16:44	Jagan	feature/auto-delete-after-delivery — daily expired-query deletion job
4	9da2532	2026-05-13 16:24	Jagan	feature/agent-logging-stdout — agent question log + stdout severity fix
5	a468e3d	2026-05-13 15:13	Jagan	feature/identify-firebase-fallback — fix fresh-signup login flow
6	d1edc6d	2026-05-13 13:13	Jagan	feature/query-log-redaction — Django log filter strips user query content before Cloud Logging
7	39a4056	2026-05-13 12:53	Jagan	feature/cloud-kms-cmek — CMEK on GCS bucket via Cloud KMS data-key
8	f9cc2c1	2026-05-13 12:11	Jagan	feature/rate-limiting — per-IP rate limiting on auth endpoints

Each row above contains every field required by section 2: change SHA, change summary, environment (always prod — main is wired to the Cloud Build production trigger), deploy time, operator, and status (only successful merges land on main; failed CI blocks the merge). The corresponding Cloud Build runs are listed on the companion CI/CD page.