Environment Secrets & Permissions

This page defines how deployment credentials, environment variables, and cloud access are managed for practicum projects.

Our goals are:

• secure, role-based access to sensitive credentials
• clear documentation for every repo
• continuity when leadership changes across quarters

---

Access Policy (Practicum Standard)

Only specific leadership roles may hold real production secrets:

Role	Access	Notes
Professor / TPM	Full & permanent	Owns hosting accounts & billing
Lead Engineers	Temporary access	Only while actively leading the project
PMs	May hold access	Only if managing deployments or environments
Students / Contributors	No secret access	May reference secret names only

🔐 What students can do

• Use secret names in code, YAML, .env.example, and README files.
• Request a deployment build from leadership if needed.

🚫 What students cannot do

• View raw secret values
• Add or remove secrets from production hosts
• Deploy without approval

Leadership may span multiple quarters. Lead Engineers and PMs keep access only while they remain assigned to that project.

---

What Counts as a “Secret”?

Category	Examples
Database Credentials	DB password, connection strings
Deployment Keys	Platform tokens (Vercel, Render, Railway, Supabase, Neon)
API Keys	Stripe, Email, Auth providers
OAuth Credentials	Client Secret, Client ID (when private)
Webhook Secrets	Payment, messaging, or authentication systems
Encryption Keys	JWT signing secrets, session keys

Environment variables are not inherently private, but values may be.

---

Required Repo Documentation: .env.example

Every backend or deployed frontend must include an .env.example file that:

✔ Lists every environment variable name
✔ NEVER includes real values
✔ Uses placeholder values or human hints

Example:

<bash> DATABASE_URL="postgresql://USERNAME:PASSWORD@HOST:PORT/DB_NAME" JWT_SECRET="your-jwt-secret-here" SUPABASE_URL="your-service-url" SUPABASE_ANON_KEY="public-or-generated-key" <>

This file must be committed to the repo and updated each time new variables are added.

---

Configuring Secrets in GitHub Repositories

Secrets in GitHub must follow these rules:

✔ Allowed to View Secret Names

All students may see:

• the secret names
• where they are used in code or workflows

❌ Not Allowed to View Secret Values

Only TPM/Professor/Active Leadership may view or modify values.

🔧 Secret Naming Best Practices

Good	Avoid
DATABASE_URL	prod_db_pw
JWT_SECRET	secret123
SUPABASE_SERVICE_ROLE_KEY	super_key

Names must be clear enough that anyone can configure them without knowing the value.

---

Cloud Account Ownership

All cloud services used by practicum projects must belong to:

🛡 A school-owned or org-owned account, not a student’s personal account.

The account owner must be:

• TPM or Professor
• Billing and service owner
• Responsible for rotating credentials when leadership changes

Leadership Access Rules

• Access may be granted to current Lead Engineers and PMs
• Access must be revoked when leadership ends
• Production secrets should NOT be rotated unless a risk is suspected

Leadership changes do NOT automatically require secret rotation, unless misuse or compromise is suspected.

---

Sharing Secrets Securely

Secrets must never be shared over:

• Slack channels
• GitHub comments
• Email
• Google Docs
• Classroom chats

Approved sharing methods:

• Direct secure message from TPM/Professor
• Password manager sharing (if available)
• Hosted platform UI with auto-generated keys (not copyable)

Never store secrets locally unless needed for deployment, and remove them when leadership ends.

---

Summary of Responsibilities

Responsibility	Who Owns It
Create/Store Secrets	TPM / Professor
Document Variable Names	All developers
Inject Secrets for Deployments	TPM / Professor / Active Leadership
Update .env.example	Implementing developer
Revoke Access When Roles Change	TPM / Professor

---