Vercel Integration
Connect Astrolabe to Vercel for seamless deployment monitoring and project management
Vercel Integration
Connect your Vercel account to Astrolabe for native desktop access to deployments, environment variables, and project management.
Features
- OAuth Authentication: Secure one-click connection to your Vercel account
- Deployment Monitoring: Real-time status updates for all your deployments
- Environment Variables: Create and manage env vars directly from the desktop app
- Project Linking: Automatically connect local repositories to Vercel projects
- Team Support: Access projects across your personal account and teams
- Build Logs: View deployment logs and error details
Prerequisites
- Astrolabe v0.1.12 or later
- Active Vercel account (Free, Pro, or Enterprise)
- macOS 15.0 or later
Setup
Option 1: OAuth (Recommended)
OAuth provides the most secure and seamless integration experience.
Open Settings
Launch Astrolabe and navigate to Settings → Integrations.
Click "Link your Vercel account"
Find the Vercel section and click the "Link your Vercel account" button.
Authorize in Browser
Your browser will open to Vercel's authorization page. Review the permissions and click "Authorize".
Scopes requested:
- Read integration configuration
- Read deployments
- Read projects
- Write project environment variables
- Read teams
- Read current user
Return to Astrolabe
After authorizing, you'll be automatically redirected back to Astrolabe. Your token will be securely saved.
Start Using Vercel
Go to any project page and click the Vercel service button to link your local project to a Vercel deployment.
Option 2: Personal Access Token
If OAuth is not configured, you can use a personal access token.
Generate Token
- Go to vercel.com/account/tokens
- Click "Create Token"
- Give it a name like "Astrolabe Desktop"
- Click "Create" and copy the token
Add to Astrolabe
- Open Settings → Integrations
- Find the Vercel section
- Paste your token in the API Token field
- The token is automatically saved
Usage
Linking a Project
Open Project
Navigate to your project in Astrolabe's sidebar.
Click Vercel Button
In the Service Integrations section, click the Vercel connection button.
Select Deployment
Choose the Vercel project you want to link from the dropdown list. Projects are automatically fetched from your Vercel account.
Confirm
Click "Link Project" to establish the connection.
Viewing Deployments
Once linked, you can:
- View deployment status in real-time on the project detail page
- Monitor build progress with live status indicators
- Access deployment URLs by clicking on deployment cards
- View error logs when builds fail
Managing Environment Variables
Go to Project Settings
Click the settings icon on your project detail page.
Navigate to Environment Variables
Select the Environment Variables tab.
Add or Edit Variables
- Click "Add Variable" to create new env vars
- Edit existing variables by clicking the edit icon
- Delete variables you no longer need
Sync to Vercel
Changes are automatically synchronized to your Vercel project.
Team Projects
If you're part of a Vercel team:
- Your teams are automatically detected during OAuth
- Team projects appear in the project selection dropdown
- Team-scoped environment variables are supported
- Use the
teamIdparameter in API calls (handled automatically)
Troubleshooting
OAuth Authorization Fails
Issue: Browser opens but redirect doesn't work.
Solution:
- Ensure Astrolabe is running when authorizing
- Check that the redirect URI is set to
https://astrolabe.dev/api/oauth/vercel/callbackin your Vercel integration settings - Try restarting Astrolabe and authorizing again
Projects Not Loading
Issue: Dropdown shows no projects after linking account.
Solution:
- Verify your token has the correct scopes
- Check that you have projects in your Vercel account
- Try re-authenticating via OAuth or regenerating your token
Environment Variables Not Syncing
Issue: Changes in Astrolabe don't appear in Vercel dashboard.
Solution:
- Ensure you have write permissions for project environment variables
- Check that the project is correctly linked
- Verify your OAuth token hasn't expired
"Invalid Token" Error
Issue: API calls fail with authentication errors.
Solution:
- Your token may have expired or been revoked
- Go to Settings → Integrations → Vercel
- Click "Link your Vercel account" again to re-authenticate
API Reference
Astrolabe uses the following Vercel API endpoints:
- OAuth Token Exchange:
POST /v2/oauth/access_token - List Projects:
GET /v9/projects - Get Project:
GET /v9/projects/:id - List Deployments:
GET /v6/deployments - Get Deployment:
GET /v13/deployments/:id - Create Environment Variable:
POST /v10/projects/:id/env
All API calls include:
- Bearer token authentication
- Automatic team context switching
- Error handling with user-friendly messages
Security
- OAuth tokens are stored encrypted in Tauri's plugin-store
- Personal access tokens are stored locally and never transmitted except to Vercel
- Deep link callbacks use the
astrolabe://protocol for secure redirects - PKCE is not used (Vercel uses standard OAuth 2.0 with client secret)
Support
Need help with the Vercel integration?