Connect GitHub and Vercel

Tekspaz connects directly to your developer tools so code created by agents lands in your Git repositories and deploys automatically to your cloud hosting.

Connecting GitHub and Vercel enables automated branch management, pull request creation, preview deployments, and seamless production shipping.

---

1. Connecting GitHub

Connecting GitHub gives Tekspaz permission to create working branches, push verified commits, and open pull requests in your repositories.

Installation Steps

1. Sign in to Tekspaz and open Settings › Connections (/settings).
2. Locate the GitHub card and click Connect GitHub.
3. You will be redirected to GitHub to authorize the Tekspaz GitHub App:
   • Personal Account or Organization: Choose which account or GitHub Organization to install the app onto.
   • Repository Access:
     • All repositories: Recommended if your team builds multiple new projects through Tekspaz.
     • Only select repositories: Select specific repositories you wish to grant access to.
4. Click Install & Authorize.
5. GitHub will redirect you back to Tekspaz Settings with a confirmation notice: Connected to GitHub as @your-handle.

sequenceDiagram
    autonumber
    actor Admin as Workspace Admin
    participant Teks as Tekspaz Platform
    participant GH as GitHub API
    Admin->>Teks: Click "Connect GitHub"
    Teks->>GH: Redirect to GitHub App Installation
    Admin->>GH: Select Repositories & Grant Permissions
    GH->>Teks: OAuth Callback with Installation ID
    Teks->>Teks: Store Encrypted Installation Token
    Teks-->>Admin: Show "Connected as @handle"

Required Permissions

The Tekspaz GitHub App requests minimum necessary permissions:

• Repository contents: Read & write (to create branches and push agent-written code).
• Pull requests: Read & write (to open and update pull requests for human review).
• Workflows: Read & write (to trigger and inspect GitHub Actions runs).
• Metadata: Read-only (mandatory GitHub requirement).

---

2. Connecting Vercel

Connecting Vercel enables TeksBuild to provision preview environments and trigger production releases without manual export.

Configuration Steps

1. In Tekspaz, go to Settings › Connections (/settings).
2. In the Vercel section, you will need two credentials:
   • Vercel Access Token:
     • Navigate to vercel.com/account/tokens.
     • Click Create Token.
     • Set Scope to your team or account and give it an expiration policy.
     • Copy the generated token (Bearer ...).
   • Vercel Team ID (Optional for personal accounts):
     • Found in your Vercel Team Settings under General › Team ID (e.g. team_abc123).
3. Paste your token and Team ID into the Tekspaz Vercel connection form.
4. Click Save & Verify Connection.
5. Tekspaz will verify connectivity against Vercel’s API (/v2/user or /v2/teams) and display a green checkmark.

---

3. Synchronizing Environment Variables & Secrets

Real applications require secrets such as database URLs, payment keys, or third-party client IDs. Tekspaz provides end-to-end encrypted secret synchronization:

1. In your project dashboard, navigate to Settings › Environment Variables.
2. Click Add Variable:
   • Key: e.g. DATABASE_URL
   • Value: postgresql://user:pass@host.db.example.com:5432/main
   • Target: Check Preview, Development, and/or Production.
3. All secrets are encrypted at rest using libsodium seal encryption before storage.
4. When TeksBuild triggers a Vercel deployment, it automatically mirrors these environment variables to your linked Vercel project via Vercel’s Project Secrets API.

---

4. End-to-End Pipeline Verification

To verify that your connections are healthy:

1. Open an existing project or create a quick test project.
2. In the project conversation, submit a small change (e.g. “Update footer copyright year to 2026”).
3. Approve the resulting Plan Bundle.
4. In the Review screen:
   • Observe that a new Git branch is created on GitHub: tekspaz/feature-....
   • Observe the live Vercel Preview URL generated directly on the build card.
5. Click Approve Code and Deploy to Vercel.
6. Check your GitHub repository to confirm the pull request is merged, and check Vercel to confirm the production build is live!

---

5. Troubleshooting Integrations

Issue: GitHub Token Expired or Revoked

• Symptoms: 401 Unauthorized: Bad credentials when pushing code to GitHub.
• Resolution: Go to Settings › Connections, click Disconnect GitHub, then click Connect GitHub to re-authorize the app.

Issue: Repository Not Visible in Project Dropdown

• Symptoms: Your newly created GitHub repository does not appear in Tekspaz.
• Resolution: Open your GitHub Installed Applications settings, click Tekspaz App, and ensure the new repository is checked under Repository access.

Issue: Vercel Deploy Hook Timeout

• Symptoms: Deployment failed: Vercel API timed out waiting for build completion.
• Resolution: Verify in your Vercel Dashboard that your project does not exceed maximum function duration limits. Ensure astro.config.mjs sets adapter: vercel({ maxDuration: 300 }).

---

What to explore next

• TeksBuild: running builds, tests, and preview sandboxes
• TeksInfra: install the InfraOps worker and connect dbt/Snowflake
• FAQ and troubleshooting