feat(docs): add API deployment migration guide by amondnet · Pull Request #326 · amondnet/vercel-action

amondnet · 2026-03-29T10:27:02Z

Summary

Add migration guide section to README for the CLI → API transition (refactor: migrate to API-based deployment #325)
Include vercel-args to API inputs mapping table
Document deprecated inputs (vercel-args, scope)
Provide step-by-step migration instructions and CLI fallback option
Migrate example workflows to prebuilt deployment

Relates to #325

Test plan

README renders correctly on GitHub
All YAML examples are valid

gemini-code-assist · 2026-03-29T10:27:08Z

Note

Gemini is unable to generate a review for this pull request due to the file types involved not being currently supported.

github-actions · 2026-03-29T10:27:38Z

Deploy preview for team-scope-test ready!

Project:	`team-scope-test`
Status:	✅ Deploy successful!
Preview URL:	https://team-scope-test-g682pfxee-dietfriends.vercel.app
Latest Commit:	`f807277`

Deployed with vercel-action

cubic-dev-ai

1 issue found across 4 files

Prompt for AI agents (unresolved issues)


Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name=".github/workflows/example-static.yml">

<violation number="1" location=".github/workflows/example-static.yml:70">
P1: Pushes to `feature/*` branches will now be deployed as production (`--prod`) instead of preview. The old shell-script logic only set `--prod` for `refs/heads/master`, but the new conditional `github.event_name == 'push'` matches all push events including feature branches.</violation>
</file>

Architecture diagram

sequenceDiagram
    participant GHA as GitHub Actions Runner
    participant FS as Local Filesystem
    participant VAPI as Vercel Cloud API

    Note over GHA,VAPI: Prebuilt Deployment Flow (Preview & Production)

    GHA->>GHA: Setup Node.js & pnpm
    GHA->>FS: pnpm install (frozen-lockfile)

    rect rgb(240, 240, 240)
        Note right of GHA: NEW: Environment Sync Phase
        GHA->>VAPI: NEW: vercel pull (with VERCEL_TOKEN, ORG_ID, PROJECT_ID)
        VAPI-->>GHA: Project settings & environment variables
        GHA->>FS: Write to .vercel/project.json & .env
    end

    alt Trigger: pull_request_target
        GHA->>GHA: NEW: vercel build (Preview)
        GHA->>FS: Generate artifacts in .vercel/output
        GHA->>GHA: Execute Vercel Action
        GHA->>VAPI: CHANGED: vercel deploy --prebuilt
    else Trigger: push (main/master)
        GHA->>GHA: NEW: vercel build --prod (Production)
        GHA->>FS: Generate artifacts in .vercel/output
        GHA->>GHA: Execute Vercel Action
        GHA->>VAPI: CHANGED: vercel deploy --prod --prebuilt
    end

    VAPI-->>GHA: Return Deployment URL & Metadata
    GHA->>GHA: Post deployment alias/commenting

_{Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review.}

Copilot

Pull request overview

Migrates the repository’s example GitHub Actions workflows to a consistent Vercel “pull → build → deploy --prebuilt” deployment flow, aligning examples with the action’s prebuilt deployment capabilities.

Changes:

Add pnpm/Node setup and a vercel pull step to each example workflow.
Split preview vs production builds into explicit conditional steps.
Switch deployments to --prebuilt and remove vercel-org-id from action inputs in examples.

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 7 comments.

File	Description
.github/workflows/example-angular.yml	Adds Vercel pull/build steps and deploys using `--prebuilt` with updated working directory.
.github/workflows/example-express-basic-auth.yml	Adds pnpm/Node setup plus Vercel pull/build and deploys prebuilt for preview/prod.
.github/workflows/example-scope.yml	Adds pnpm/Node setup, Vercel pull/build, and deploys prebuilt with team scope.
.github/workflows/example-static.yml	Adds pnpm/Node setup, Vercel pull/build, and deploys prebuilt for preview/prod with aliases.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2026-03-29T10:31:56Z

      - uses: ./
        id: now-deployment-staging
        if: github.event_name == 'pull_request_target'
        with:
          github-token: ${{ secrets.GITHUB_TOKEN }}
          vercel-token: ${{ secrets.VERCEL_TOKEN }}
-          vercel-org-id: ${{ secrets.VERCEL_ORG_ID }}
          vercel-project-id: ${{ secrets.VERCEL_PROJECT_ID_STATIC }}
+          vercel-args: --prebuilt
          working-directory: example/static


vercel-org-id was removed but vercel-project-id is still passed. In this action, providing only vercel-project-id triggers a warning and does not export VERCEL_PROJECT_ID (it only exports when both org+project are present). Either pass both inputs, set VERCEL_ORG_ID/VERCEL_PROJECT_ID on the action step (job-level env), or remove both inputs and rely entirely on the .vercel/project.json created by vercel pull.

Copilot · 2026-03-29T10:31:56Z

+      - name: Pull Vercel environment
+        run: |
+          pnpm install --frozen-lockfile
+          pnpm exec vercel pull --yes --token=${VERCEL_TOKEN}
+        working-directory: example/team-scope
+        env:
+          VERCEL_ORG_ID: ${{ secrets.VERCEL_ORG_ID_TEAM_SCOPE }}
+          VERCEL_PROJECT_ID: ${{ secrets.VERCEL_PROJECT_ID_TEAM_SCOPE }}
+          VERCEL_TOKEN: ${{ secrets.VERCEL_TOKEN }}


pnpm install is executed with working-directory: example/team-scope, but example/team-scope has no package.json. This will fail (or be pnpm-version dependent). Run pnpm install at the workspace root (or add a package.json for this example), and keep the Vercel commands scoped via working-directory.

Copilot · 2026-03-29T10:31:56Z

      - uses: ./
        id: now-deployment-staging
        if: github.event_name == 'pull_request_target'
        with:
          github-token: ${{ secrets.GITHUB_TOKEN }}
          vercel-token: ${{ secrets.VERCEL_TOKEN }}
-          vercel-org-id: ${{ secrets.VERCEL_ORG_ID_TEAM_SCOPE }}
          vercel-project-id: ${{ secrets.VERCEL_PROJECT_ID_TEAM_SCOPE }}
+          vercel-args: --prebuilt
          working-directory: example/team-scope
          scope: ${{ secrets.VERCEL_SCOPE }}


vercel-org-id was removed but vercel-project-id is still passed. In this action, providing only vercel-project-id triggers a warning and does not export VERCEL_PROJECT_ID (it only exports when both org+project are present). Either pass both inputs, set VERCEL_ORG_ID/VERCEL_PROJECT_ID on the action step (job-level env), or remove both inputs and rely entirely on the .vercel/project.json created by vercel pull.

Copilot · 2026-03-29T10:31:56Z

      - uses: ./
        id: now-deployment-staging
        if: github.event_name == 'pull_request_target'
        with:
          github-token: ${{ secrets.GITHUB_TOKEN }}
          vercel-token: ${{ secrets.VERCEL_TOKEN }}
-          vercel-org-id: ${{ secrets.VERCEL_ORG_ID }}
          vercel-project-id: ${{ secrets.VERCEL_PROJECT_ID_AUTH }}
+          vercel-args: --prebuilt
          working-directory: example/express-basic-auth


vercel-org-id was removed but vercel-project-id is still passed. In this action, providing only vercel-project-id triggers a warning and does not export VERCEL_PROJECT_ID (it only exports when both org+project are present). Either pass both inputs, set VERCEL_ORG_ID/VERCEL_PROJECT_ID on the action step (job-level env), or remove both inputs and rely entirely on the .vercel/project.json created by vercel pull.

Copilot · 2026-03-29T10:31:57Z

      - uses: ./
        id: vercel-action-staging
        if: github.event_name == 'pull_request_target'
        with:
          github-token: ${{ secrets.GITHUB_TOKEN }}
          vercel-token: ${{ secrets.VERCEL_TOKEN }}
-          vercel-org-id: ${{ secrets.VERCEL_ORG_ID }}
          vercel-project-id: ${{ secrets.VERCEL_PROJECT_ID_ANGULAR }}
-          working-directory: example/angular/dist/angular
+          vercel-args: --prebuilt
+          working-directory: example/angular
          alias-domains: |


vercel-org-id was removed but vercel-project-id is still passed. In this action, providing only vercel-project-id triggers a warning and does not export VERCEL_PROJECT_ID (it only exports when both org+project are present). Either pass both inputs, set VERCEL_ORG_ID/VERCEL_PROJECT_ID on the action step (job-level env), or remove both inputs and rely entirely on the .vercel/project.json created by vercel pull.

Copilot · 2026-03-29T10:31:57Z

+      - name: Pull Vercel environment
+        run: |
+          pnpm install --frozen-lockfile
+          pnpm exec vercel pull --yes --token=${VERCEL_TOKEN}


pnpm install is executed with working-directory: example/static, but example/static has no package.json. pnpm will fail in directories without a manifest (or behave inconsistently across versions). Run pnpm install at the repo/workspace root (or add a package.json for this example), and keep the Vercel commands scoped via working-directory.

Suggested change

- name: Pull Vercel environment

run: |

pnpm install --frozen-lockfile

pnpm exec vercel pull --yes --token=${VERCEL_TOKEN}

- name: Install dependencies

run: pnpm install --frozen-lockfile

- name: Pull Vercel environment

run: pnpm exec vercel pull --yes --token=${VERCEL_TOKEN}

Copilot · 2026-03-29T10:31:57Z

+      - name: Build (production)
+        if: github.event_name == 'push'
+        run: pnpm exec vercel build --prod
+        working-directory: example/static
        env:
-          REF: ${{ github.ref }}
+          VERCEL_ORG_ID: ${{ secrets.VERCEL_ORG_ID }}
+          VERCEL_PROJECT_ID: ${{ secrets.VERCEL_PROJECT_ID_STATIC }}
      - uses: ./
        id: now-deployment-production
        if: github.event_name == 'push'
        with:
          github-token: ${{ secrets.GITHUB_TOKEN }}
          vercel-token: ${{ secrets.VERCEL_TOKEN }}
-          vercel-org-id: ${{ secrets.VERCEL_ORG_ID }}
          vercel-project-id: ${{ secrets.VERCEL_PROJECT_ID_STATIC }}
-          vercel-args: ${{ steps.prod_or_not.outputs.vercel-args }}
+          vercel-args: --prod --prebuilt
          working-directory: example/static


This workflow runs on push to both master and feature/*, but the production deploy step always uses vercel-args: --prod --prebuilt. That will create production deployments from feature branches (regression vs the previous branch check). Add a ref check so --prod is only used on the default branch, and deploy previews for other pushed branches (or remove feature/* from the push trigger).

- Add vercel pull -> vercel build -> vercel deploy --prebuilt flow - Add pnpm/node setup steps where missing - Remove vercel-org-id input (now set via env vars in pull step) - Separate preview/production builds with conditional steps - Replace shell script for prod_or_not with explicit conditional build steps

Add migration guide section to README documenting the transition from CLI-based to API-based deployment introduced in #325. Includes vercel-args to API inputs mapping table, step-by-step migration instructions, and deprecated inputs reference.

sonarqubecloud · 2026-04-02T07:03:44Z

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

cubic-dev-ai

0 issues found across 1 file (changes from recent commits).

_{Auto-approved: Documentation update and migration guide for API-based deployment. Updates example workflows to follow current best practices for prebuilt deployments. No changes to core action logic.}

Copilot AI review requested due to automatic review settings March 29, 2026 10:27

Copilot started reviewing on behalf of amondnet March 29, 2026 10:27 View session

cubic-dev-ai Bot reviewed Mar 29, 2026

View reviewed changes

Comment thread .github/workflows/example-static.yml

Copilot AI reviewed Mar 29, 2026

View reviewed changes

amondnet added 2 commits April 2, 2026 15:54

amondnet force-pushed the amondnet/puzzle-mochi branch from f807277 to d515e66 Compare April 2, 2026 07:02

amondnet changed the title ~~refactor(example): migrate all example workflows to prebuilt deployment~~ feat(docs): add API deployment migration guide Apr 2, 2026

docs: update action version references from v25 to v42

9007ca4

cubic-dev-ai Bot approved these changes Apr 2, 2026

View reviewed changes

Uh oh!

Conversation

amondnet commented Mar 29, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Test plan

Uh oh!

gemini-code-assist Bot commented Mar 29, 2026

Uh oh!

github-actions Bot commented Mar 29, 2026

Uh oh!

cubic-dev-ai Bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Copilot AI Mar 29, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 29, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 29, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 29, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 29, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 29, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 29, 2026

Choose a reason for hiding this comment

Uh oh!

sonarqubecloud Bot commented Apr 2, 2026

Quality Gate passed

Uh oh!

cubic-dev-ai Bot left a comment

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

amondnet commented Mar 29, 2026 •

edited

Loading