4.4 KiB
Secrets Contract
Last updated: 2026-05-09
This file describes secret ownership, storage, and rotation for the manual launch path.
Storage Rules
Primary runtime storage:
- server-side env files generated from
.env.gitgram.example,.env.gitgram-web.example,.env.aitm-api.example - optional
.env.aitm-websiteif you self-host the AITM dashboard
Optional storage for future automation:
- GitHub Actions secrets and environment variables
Rules:
- Do not commit populated
.envfiles. - Do not rely on GitHub Actions secrets as the only production source of truth for a manual launch.
- Use separate values for staging and production.
- Use separate product-scoped credentials where providers allow it.
Launch-Critical Secrets
Gitgram
| Secret | Purpose | Rotate |
|---|---|---|
DATABASE_URL |
PostgreSQL connection | on DB credential change |
REDIS_URL |
Redis connection | on Redis credential change |
JWT_SECRET |
access-token signing | every 90 days |
JWT_REFRESH_SECRET |
refresh-token signing | every 90 days |
GITHUB_CLIENT_SECRET |
GitHub OAuth | on compromise |
POLAR_ACCESS_TOKEN |
billing API | on compromise |
POLAR_WEBHOOK_SECRET |
billing webhook verification | on endpoint re-creation |
RESEND_API_KEY |
transactional email | on compromise |
SENTRY_DSN |
error reporting | when project changes |
Conditional:
AWS_ACCESS_KEY_IDAWS_SECRET_ACCESS_KEY
These are required only when STORAGE_TYPE=s3.
Gitgram Web
The launch-critical web vars are mostly public build inputs, not secrets.
Non-secret public values:
NEXT_PUBLIC_API_URLNEXT_PUBLIC_WS_URLNEXT_PUBLIC_GITHUB_CLIENT_ID
Optional public values:
NEXT_PUBLIC_GOOGLE_CLIENT_IDNEXT_PUBLIC_AITM_API_URLNEXT_PUBLIC_SENTRY_DSN
AITM API
| Secret | Purpose | Rotate |
|---|---|---|
DATABASE_URL |
PostgreSQL / Neon connection | on DB credential change |
INTERNAL_SECRET |
internal website-to-API auth | every 90 days |
POLAR_ACCESS_TOKEN |
billing API | on compromise |
POLAR_WEBHOOK_SECRET |
billing webhook verification | on endpoint re-creation |
RESEND_API_KEY |
transactional email | on compromise |
SENTRY_DSN |
error reporting | when project changes |
Optional after launch:
CLERK_WEBHOOK_SECRETOPENAI_API_KEYANTHROPIC_API_KEYVOYAGE_API_KEYBRAVE_SEARCH_API_KEYAWS_ACCESS_KEY_IDAWS_SECRET_ACCESS_KEY
AITM npm Release Flow
Manual publish:
- operator npm session from
npm login
CI release:
- GitHub secret
NPM_TOKEN
Note:
- the release workflow maps
NPM_TOKENintoNODE_AUTH_TOKEN - it currently covers
@gitgram/timemachine, not the MCP package
Optional Self-Hosted AITM Website
Only needed if you run aitimemachine/website yourself.
Secrets:
CLERK_SECRET_KEYINTERNAL_SECRETPOLAR_ACCESS_TOKEN
Public build inputs:
NEXT_PUBLIC_CLERK_PUBLISHABLE_KEYNEXT_PUBLIC_API_URLAPI_URLNEXT_PUBLIC_APP_URLNEXT_PUBLIC_POLAR_PRO_PRODUCT_IDNEXT_PUBLIC_POLAR_TEAM_PRODUCT_ID
Shared Secret Policy
AWS
Prefer separate IAM users:
- Gitgram S3 user: media bucket only
- AITM S3 user: knowledge-base bucket only
Redis
A shared Redis instance is acceptable.
- Gitgram uses it for cache/session concerns.
- AITM uses it only when optional distributed rate limiting is enabled.
Resend
Prefer separate API keys under the same account:
- one key for Gitgram
- one key for AITM
Sentry
Use separate projects and DSNs for Gitgram and AITM.
Rotation Checklist
JWT-style secrets:
openssl rand -base64 64
Recommended process:
- rotate in staging first
- redeploy staging and verify
- rotate production
- redeploy production
- record the date and owner
Database URLs:
- rotate credentials at the provider
- update the server env file
- restart the affected service
- verify health endpoints
Webhook secrets:
- recreate or rotate in the provider dashboard
- update the matching env file
- restart the service
- verify one live webhook
What Can Wait Until After Launch
These are explicitly not part of the first-launch blocker set:
- Google OAuth for Gitgram
- AITM AI provider keys
- AITM web-search provider keys
- AITM Redis
- AITM S3 / knowledge-base offload
- optional self-hosted AITM website
Validation
Use:
bash scripts/validate-prod-secrets.sh production
That script is the repo-level preflight check for the manual launch contract.