CNC Lab Deployment Setup Guide

This guide covers setting up automatic deployments that work for all team members, including the transition from personal to lab Vercel accounts.

Overview¶

Currently, your lab website is under your personal Vercel account, which requires $20/month per user for team deployments. This setup bypasses that limitation and works seamlessly during account transfers.

Token Strategy¶

Current Phase (Personal Account)¶

VERCEL_TOKEN=your_personal_vercel_token
GITHUB_TOKEN=organization_fine_grained_token

Future Phase (After Transfer to Lab Account)¶

VERCEL_TEAM_TOKEN=lab_vercel_team_token  
GITHUB_ORG_TOKEN=organization_fine_grained_token  # Same token!

The script automatically checks for both token names, so no code changes needed during transfer.

Token Setup Instructions¶

1. GitHub Organization Token (Do This Once, Works Forever)¶

Create a Fine-Grained Personal Access Token at organization level:

1. Go to: https://github.com/organizations/CNClaboratory/settings/personal-access-tokens/tokens

2. Click “Generate new token”

3. Configure:

   • Name: CNC Lab Deployment Automation

   • Expiration: 1 year (or custom)

   • Repository access: All repositories or select specific ones

   • Repository permissions:

     • Contents: Read and write ✅

     • Issues: Read ✅ (future automation)

     • Pull requests: Read and write ✅ (future automation)

     • Webhooks: Write ✅ (required)

     • Actions: Read ✅ (monitoring)

     • Metadata: Read ✅ (required)

Why Organization Token?

• ✅ Survives personnel changes

• ✅ Organization audit trail

• ✅ Centralized management

• ✅ Works across all lab repositories

2. Vercel Token (Changes During Transfer)¶

Current Setup (Personal Account)¶

1. Go to: https://vercel.com/account/tokens

2. Create token: CNC Lab Deploy Hooks

3. Copy token → set as VERCEL_TOKEN

After Transfer (Lab Account)¶

1. Go to: https://vercel.com/teams/[lab-team]/settings/tokens

2. Create token: CNC Lab Deploy Hooks

3. Copy token → set as VERCEL_TEAM_TOKEN

Running the Setup¶

One-Time Setup¶

# Set environment variables (use your actual tokens)
export VERCEL_TOKEN="your_vercel_token_here"
export GITHUB_TOKEN="your_github_org_token_here"

# Run the automated setup
node setup-deploy-hooks.js

What It Does¶

1. 🔍 Discovers all your Vercel projects

2. 🪝 Creates Deploy Hooks for CNC Lab projects (filters by name)

3. 🔗 Sets up GitHub webhooks to trigger on every push

4. ✅ Tests the configuration

Expected Output¶

🚀 Starting automated deploy hook setup...

🔧 Token Configuration:
   - Using Vercel token: ✅ Found
   - Using GitHub token: ✅ Found  
   - Target: CNClaboratory/cnclab_website

🔍 Getting Vercel projects...
Found 2 Vercel projects

📦 Processing project: cnclab-website
🪝 Creating deploy hook for cnclab-website...
✅ Deploy hook created: https://api.vercel.com/v1/integrations/deploy/...
🔗 Creating GitHub webhook for cnclab-website...  
✅ GitHub webhook created with ID: 12345

📦 Processing project: cnclab-docs
🪝 Creating deploy hook for cnclab-docs...
✅ Deploy hook created: https://api.vercel.com/v1/integrations/deploy/...
🔗 Creating GitHub webhook for cnclab-docs...
✅ GitHub webhook created with ID: 67890

🎉 All done! Your repositories will now auto-deploy on every push to master branch.

🧪 Test it by making a commit and pushing to GitHub!

Account Transfer Checklist¶

When you’re ready to transfer to a lab Vercel account:

Before Transfer¶

• Current setup is working (all team members can trigger deployments)

• Document current project configurations

• Note down any custom environment variables

During Transfer¶

• Create new Vercel team account

• Transfer all projects to team account

• Generate new team-level Vercel token

• Update environment variable: VERCEL_TOKEN → VERCEL_TEAM_TOKEN

After Transfer¶

• Re-run setup script with new token

• Test deployments from multiple team members

• Update documentation with team URLs

Benefits of This Approach¶

✅ Cost Savings: No $20/month per user fees
✅ Seamless Transfer: GitHub token doesn’t change
✅ Future-Proof: Works with any Vercel account structure
✅ Team Scalable: Add unlimited team members for free
✅ Production Ready: Proper error handling and logging

Troubleshooting¶

“Deploy hook created but deployments not triggering”

• Check webhook was created in GitHub repo settings

• Verify webhook URL matches deploy hook URL

• Test webhook with “Recent Deliveries” in GitHub

“Projects not found”

• Script looks for projects containing: “cnc”, “lab”, “website”, “docs”

• If your projects have different names, modify the filter in the script

“Token permissions error”

• Verify GitHub token has all required scopes

• Ensure Vercel token belongs to account that owns the projects

Security Notes¶

• Store tokens in environment variables, never in code

• Use minimal required permissions

• Rotate tokens annually

• Use organization-level tokens for longevity

• Remove tokens when no longer needed

Support¶

If you encounter issues during setup or transfer:

1. Check the troubleshooting section above

2. Verify all tokens have correct permissions

3. Test individual API endpoints manually

4. Review Vercel and GitHub webhook logs