Vercel

Discovery

Discover and manage Vercel teams, projects, and deployments in your Devgraph knowledge graph.

Overview

The Vercel molecule connects to Vercel's API to automatically discover teams, projects, and deployments. It creates entities and intelligent relationships that link Vercel projects to their source repositories.

Key Features:

• Discover teams, projects, and deployments
• Filter projects by name patterns (regex)
• Link projects to source repositories (GitHub, GitLab)
• Track deployment history (5 most recent deployments per project)
• Support for both team and personal projects

Quick Start

providers:
  - name: vercel
    type: vercel
    every: 300  # Reconcile every 5 minutes
    config:
      namespace: default
      api_url: https://api.vercel.com
      token: ${VERCEL_TOKEN}
      team_id: team_abc123
      selectors:
        - project_name_pattern: ".*"  # All projects

Configuration

Basic Configuration

providers:
  - name: vercel-prod
    type: vercel
    every: 300
    config:
      namespace: production
      api_url: https://api.vercel.com
      token: ${VERCEL_TOKEN}
      team_id: team_abc123
      selectors:
        - project_name_pattern: "frontend-.*"
        - project_name_pattern: "backend-.*"

Personal Projects

For personal (non-team) projects, omit or set team_id to null:

providers:
  - name: vercel-personal
    type: vercel
    every: 300
    config:
      namespace: default
      token: ${VERCEL_TOKEN}
      team_id: null  # Personal projects
      selectors:
        - project_name_pattern: ".*"

Multi-Team Configuration

providers:
  - name: vercel-team-a
    type: vercel
    every: 300
    config:
      namespace: team-a
      token: ${VERCEL_TOKEN_A}
      team_id: team_abc123
      selectors:
        - project_name_pattern: ".*"

  - name: vercel-team-b
    type: vercel
    every: 300
    config:
      namespace: team-b
      token: ${VERCEL_TOKEN_B}
      team_id: team_def456
      selectors:
        - project_name_pattern: ".*"

Configuration Options

Option	Type	Required	Default	Description
namespace	string	No	default	Namespace for created entities
api_url	string	No	https://api.vercel.com	Vercel API endpoint
token	string	Yes	-	Vercel authentication token
team_id	string	No	null	Vercel team ID (null for personal)
timeout	integer	No	30	Request timeout in seconds
selectors	list	No	[{project_name_pattern: ".*"}]	Project selectors

Selector Options

Each selector specifies which projects to discover:

Option	Type	Required	Default	Description
team_id	string	No	-	Override provider-level team_id
project_name_pattern	string	No	.*	Regex pattern for project names

Authentication

Creating a Vercel Token

1. Go to Vercel Account Settings → Tokens
2. Click "Create Token"
3. Give it a name (e.g., "Devgraph Integration")
4. Select scope:
   • Full Account or specific teams
5. Click "Create"
6. Copy the token

Set environment variable:

export VERCEL_TOKEN="your-token-here"

Finding Your Team ID

1. Go to your team dashboard on Vercel
2. Look at the URL: https://vercel.com/team/YOUR_TEAM_SLUG
3. Or use Vercel CLI:

vercel teams ls

Entities Created

VercelTeam

Represents a Vercel team/organization.

Entity Structure:

apiVersion: entities.devgraph.ai/v1
kind: VercelTeam
metadata:
  name: my-team
  namespace: default
  labels:
    team_id: team_abc123
spec:
  id: team_abc123
  slug: my-team
  name: My Team
  avatar: https://vercel.com/api/www/avatar/...
  created_at: "2022-01-01T00:00:00Z"

Fields:

• id: Team ID
• slug: Team URL slug
• name: Team display name
• avatar: Team avatar URL
• created_at: Team creation timestamp

VercelProject

Represents a Vercel project.

Entity Structure:

apiVersion: entities.devgraph.ai/v1
kind: VercelProject
metadata:
  name: my-frontend
  namespace: default
  labels:
    project_id: prj_abc123
    team_id: team_def456
spec:
  name: my-frontend
  id: prj_abc123
  framework: nextjs
  url: https://my-frontend.vercel.app
  description: My awesome Next.js app
  team_id: team_def456
  created_at: "2023-01-01T00:00:00Z"
  updated_at: "2024-01-15T10:30:00Z"
  link:
    type: github
    repo: myorg/my-frontend
    org: myorg

Key Fields:

• id: Project ID
• name: Project name
• framework: Framework used (nextjs, vite, etc.)
• url: Production URL
• description: Project description
• team_id: Team that owns the project
• link: Source repository information

VercelDeployment

Represents a deployment (limited to 5 most recent per project).

Entity Structure:

apiVersion: entities.devgraph.ai/v1
kind: VercelDeployment
metadata:
  name: my-frontend-abc12345
  namespace: default
  labels:
    project_id: prj_abc123
    deployment_uid: dpl_abc12345
    state: READY
spec:
  uid: dpl_abc12345
  name: my-frontend
  url: https://my-frontend-abc12345.vercel.app
  project_id: prj_abc123
  state: READY
  type: LAMBDA
  target: production
  created_at: "2024-01-15T10:30:00Z"
  ready: true

Key Fields:

• uid: Deployment unique ID
• name: Project name
• url: Deployment URL
• state: Deployment state (READY, ERROR, etc.)
• type: Deployment type (LAMBDA, etc.)
• target: Target environment (production, preview)
• ready: Whether deployment is ready

Relationships

BELONGS_TO (Project → Team)

Projects belong to teams.

VercelProject --BELONGS_TO--> VercelTeam

Example:

my-frontend --BELONGS_TO--> my-team

BELONGS_TO (Deployment → Project)

Deployments belong to projects.

VercelDeployment --BELONGS_TO--> VercelProject

Example:

my-frontend-abc12345 --BELONGS_TO--> my-frontend

USES (Project → Repository)

Projects are linked to their source repositories (field-selected relation).

VercelProject --USES--> GithubRepository
VercelProject --USES--> GitlabProject

Example:

my-frontend --USES--> myorg/my-frontend (GitHub)

Filtering Projects

Match All Projects

project_name_pattern: ".*"

Match Prefix

project_name_pattern: "frontend-.*"

Match Suffix

project_name_pattern: ".*-web"

Multiple Patterns

selectors:
  - project_name_pattern: "frontend-.*"
  - project_name_pattern: "backend-.*"

Use Cases

Multi-Environment Discovery

# Production projects
- name: vercel-prod
  config:
    namespace: production
    team_id: team_prod
    selectors:
      - project_name_pattern: "prod-.*"

# Staging projects
- name: vercel-staging
  config:
    namespace: staging
    team_id: team_staging
    selectors:
      - project_name_pattern: "staging-.*"

Team-Based Organization

selectors:
  - project_name_pattern: "frontend-.*"
  - project_name_pattern: "landing-.*"
  - project_name_pattern: "docs-.*"

Personal and Team Projects

# Team projects
- name: vercel-team
  config:
    namespace: team
    team_id: team_abc123

# Personal projects
- name: vercel-personal
  config:
    namespace: personal
    team_id: null

Troubleshooting

Authentication Errors

Symptom: "401 Unauthorized" or "403 Forbidden"

Solutions:

1. Verify token is correct and not expired
2. Check token has access to the specified team
3. For team projects, ensure team_id is correct
4. Regenerate token if necessary

Team Not Found

Symptom: "Team not found" error

Solutions:

1. Verify team_id is correct
2. Check token has access to the team
3. Use Vercel CLI to list teams: vercel teams ls

Missing Projects

Symptom: Expected projects not appearing

Solutions:

1. Check project_name_pattern matches project names
2. Verify token has access to projects
3. Ensure projects exist in the specified team
4. Review logs for errors

Rate Limiting

Symptom: "429 Too Many Requests" errors

Solutions:

1. Increase reconciliation interval (every: 600)
2. Reduce number of projects with more specific patterns
3. Contact Vercel support if consistent issues

Deployment Limit

Note: By design, only the 5 most recent deployments per project are discovered to prevent overwhelming the system.

If you need more deployment history, this can be adjusted in the provider configuration.

Performance Tips

1. Use specific patterns: Filter projects at the API level
2. Adjust interval: Balance freshness vs. API usage
3. Separate teams: Use different providers for different teams
4. Deployment limit: Default 5 deployments per project is usually sufficient

Integration Examples

Link to GitHub Repositories

The Vercel molecule automatically creates field-selected relations linking projects to their GitHub repositories:

VercelProject --USES--> GithubRepository

This happens automatically when:

1. The project has GitHub as its source
2. The GitHub molecule has discovered the repository

Link to GitLab Projects

Similarly for GitLab:

VercelProject --USES--> GitlabProject

Track Production Deployments

Query production deployments:

Find all VercelDeployment where target = "production" and state = "READY"

Frameworks Supported

Vercel supports many frameworks, automatically detected:

• Next.js
• React / Vite
• SvelteKit
• Nuxt.js
• Astro
• Remix
• Angular
• Vue.js
• And many more

The framework field in VercelProject entities will reflect the detected framework.

Next Steps

• Configure GitHub molecule to link source repositories
• Set up GitLab molecule for GitLab-hosted projects
• Learn about entity relationships