docs: add Vercel deployment/redeploy runbook - #53
Conversation
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
📝 WalkthroughWalkthroughAdded Vercel deployment documentation. It defines branch protection requirements, explains production redeployment and commit deployment, and describes how to detect drift between production and ChangesDeployment documentation
Estimated code review effort: 1 (Trivial) | ~3 minutes 🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
There was a problem hiding this comment.
Pull request overview
Adds a Vercel-focused deployment/redeploy runbook to document how production deployments are managed for the Amazon Ad Console repo and to highlight the “production can drift from main” gotcha.
Changes:
- Introduces
docs/DEPLOYMENT.mdwith Vercel project details, CI/branch-protection expectations, and redeploy steps via the Vercel UI. - Documents how to verify which commit is currently aliased to production (vs. assuming
mainHEAD).
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| There is no API/CLI action available in this repo's tooling that redeploys an existing | ||
| Vercel deployment by ID or deletes a project. To redeploy production: |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 2
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@docs/DEPLOYMENT.md`:
- Around line 21-23: Update the deployment selection steps in the deployment
instructions to require confirming the deployment has the production alias and
target: production before choosing Redeploy, rather than relying on its position
at the top of the list.
- Around line 32-36: Update the production comparison instructions in
DEPLOYMENT.md to use a Vercel deployment inspection API with git repository
metadata enabled, fetch origin/main, and compare meta.githubCommitSha against
git rev-parse origin/main. State that missing meta.githubCommitSha makes the
deployment unverifiable, rather than relying on the local main branch or commit
reference.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro Plus
Run ID: c621b8c3-b1f2-4c55-914f-6330c3bc29e7
📒 Files selected for processing (1)
docs/DEPLOYMENT.md
| 1. Open https://vercel.com/ryandabao1982s-projects/amazon-ad-console/deployments | ||
| 2. Find the deployment aliased to production (top of the list, `target: production`) | ||
| 3. Open its "⋯" menu → **Redeploy** |
There was a problem hiding this comment.
🎯 Functional Correctness | 🟠 Major | ⚡ Quick win
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
set -euo pipefail
echo "== deployment.md relevant lines =="
if [ -f docs/DEPLOYMENT.md ]; then
nl -ba docs/DEPLOYMENT.md | sed -n '1,40p'
else
echo "docs/DEPLOYMENT.md not found"
fi
echo "== search for production redeploy instructions =="
rg -n "Redeploy|production alias|current production|target: production|deployments" docs .README* .git 2>/dev/null || true
echo "== changed file context =="
git diff -- docs/DEPLOYMENT.md 2>/dev/null | sed -n '1,160p' || trueRepository: projectamazonph/Amazon-ad-console
Length of output: 246
🌐 Web query:
Vercel deployments list top deployment current production order filter production alias documentation
💡 Result:
To list deployments for a Vercel project and filter by production, you use the Vercel CLI command vercel list (or vercel ls) [1][2]. To specifically filter for production deployments, use the --prod flag [1][2]: vercel list --prod Alternatively, you can use the --environment flag: vercel list --environment production [1][2] Regarding your request for "production alias" and "order" documentation: 1. Order: By default, the vercel list command displays recent deployments for the currently linked project, sorted chronologically [1][3]. The CLI does not provide a built-in flag to change this sort order; the data is returned in a standard sequence (typically newest first). 2. Production Alias (Current): Vercel tracks production deployments by status, specifically marking the deployment currently serving traffic to your production domains as "Current" [4]. You can identify this in the Vercel dashboard under the Deployments tab [5]. In the CLI, the vercel list command provides high-level status, but identifying the "Current" (aliased) production deployment is often more easily managed via the dashboard interface where you can view deployment status, perform promotions, and see domain assignments [5][4]. 3. Promotion/Alias Management: Note that vercel alias is generally considered a legacy command for promoting production traffic [6]. Vercel now recommends using vercel promote [deployment-id] for promoting staged builds to production, which handles the necessary aliasing automatically [6]. For more complex filtering, such as listing deployments by specific criteria, you can use additional flags: --status: Filter by deployment state (e.g., --status READY) [1][2]. --meta: Filter by custom metadata [1][2]. --next: Use for pagination [1][2].
Citations:
- 1: https://vercel.com/docs/cli/list
- 2: https://examples.vercel.com/docs/cli/list
- 3: https://github.com/vercel/vercel/blob/7e64cc27/packages/cli/src/commands/list/index.ts
- 4: https://vercel.com/docs/deployments/promoting-a-deployment
- 5: https://vercel.com/docs/deployments/managing-deployments
- 6: https://vercel.com/docs/cli/alias
🏁 Script executed:
#!/bin/bash
set -euo pipefail
echo "== deployment.md relevant lines =="
if command -v nl >/dev/null 2>&1; then
nl -ba docs/DEPLOYMENT.md | sed -n '1,60p'
else
awk 'BEGIN{for(i=1;i<=60;i++) printf "%6d\t", i} {print}' docs/DEPLOYMENT.md | sed -n '1,60p'
fi
echo "== search occurrences =="
rg -n "Redeploy|production alias|current production|target: production|deployments|Filter|alias" docs README* .git 2>/dev/null || true
echo "== changed file context =="
git diff -- docs/DEPLOYMENT.md 2>/dev/null | sed -n '1,180p' || trueRepository: projectamazonph/Amazon-ad-console
Length of output: 4992
Confirm the production alias before redeploying.
The deploys list order is not a stable production selector. Use the deployment’s production alias and target: production status before choosing Redeploy.
Proposed wording
-Find the deployment aliased to production (top of the list, `target: production`)
+Filter for the current production deployment. Confirm its production alias and
+`target: production` before selecting **Redeploy**.📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| 1. Open https://vercel.com/ryandabao1982s-projects/amazon-ad-console/deployments | |
| 2. Find the deployment aliased to production (top of the list, `target: production`) | |
| 3. Open its "⋯" menu → **Redeploy** | |
| 1. Open https://vercel.com/ryandabao1982s-projects/amazon-ad-console/deployments | |
| 2. Filter for the current production deployment. Confirm its production alias and | |
| `target: production` before selecting **Redeploy**. | |
| 3. Open its "⋯" menu → **Redeploy** |
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/DEPLOYMENT.md` around lines 21 - 23, Update the deployment selection
steps in the deployment instructions to require confirming the deployment has
the production alias and target: production before choosing Redeploy, rather
than relying on its position at the top of the list.
| Production is whatever deployment is currently aliased to it — that isn't always | ||
| `main`'s latest commit. A deployment can be promoted to production from any branch | ||
| (e.g. via a manual "Redeploy" of an older build, or a preview deployment promoted by | ||
| hand). Before assuming production matches `main` HEAD, check the deployment's | ||
| `meta.githubCommitRef` and `meta.githubCommitSha` against `git log main -1`. |
There was a problem hiding this comment.
🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
set -euo pipefail
echo "== docs DEPLOYMENT.md relevant lines =="
sed -n '1,80p' docs/DEPLOYMENT.md
echo
echo "== repo git references =="
if git rev-parse --verify origin/main >/dev/null 2>&1; then
git rev-parse origin/main
else
echo "origin/main not present"
fi
if git rev-parse --verify main >/dev/null 2>&1; then
git rev-parse main
else
echo "main not present"
fi
echo
echo "== search for vercel inspect references and github metadata =="
rg -n "vercel inspect|githubCommitSha|githubCommitRef|meta\\.|main HEAD|git log main|git rev-parse" . --glob '!node_modules/**' --glob '!dist/**' --glob '!build/**' || true
echo
echo "== deterministic git behavior probe =="
python3 - <<'PY'
import subprocess, tempfile, os, textwrap
repo = tempfile.mkdtemp()
subprocess.run(["git","init","--quiet"], cwd=repo, check=True)
subprocess.run(["git","config","user.name","test"], cwd=repo, check=True)
subprocess.run(["git","config","user.email","test@example.com"], cwd=repo, check=True)
p = os.path.join(repo,"README.md")
with open(p,"w") as f: f.write("a\n")
subprocess.run(["git","add","README.md"], cwd=repo, check=True)
subprocess.run(["git","commit","--quiet","-m","first"], cwd=repo, check=True)
origin = tempfile.mkdtemp()
subprocess.run(["git","init","--bare","--quiet"], cwd=origin, check=True)
subprocess.run(["git","remote","add","origin",origin], cwd=repo, check=True)
subprocess.run(["git","push","--quiet","origin","main"], cwd=repo, check=True)
subprocess.run(["git","checkout","--quiet","-b","feature"], cwd=repo, check=True)
with open(p,"w") as f: f.write("a\nb\n")
subprocess.run(["git","add","README.md"], cwd=repo, check=True)
subprocess.run(["git","commit","--quiet","-m","feature"], cwd=repo, check=True)
sha_remote = subprocess.check_output(["git","rev-parse","origin/main"], cwd=repo).decode().strip()
sha_local = subprocess.check_output(["git","rev-parse","main"], cwd=repo).decode().strip()
log_line = subprocess.check_output(["git","log","main","-1","--pretty=format:%H"], cwd=repo).decode().strip()
print({"sha_remote": sha_remote, "sha_local": sha_local, "git_log_main_hex": log_line, "local_behind": sha_local != sha_remote})
PYRepository: projectamazonph/Amazon-ad-console
Length of output: 2612
🌐 Web query:
Vercel deployment inspection githubCommitSha meta githubCommitRef vercel inspect
💡 Result:
To inspect Vercel deployments and access metadata such as the Git commit SHA (githubCommitSha) or branch reference (githubCommitRef), you can use the Vercel CLI, the Vercel REST API, or environment variables. Vercel CLI Inspection The vercel inspect <deployment-url> command provides general information about a deployment, such as its URL, status, and creation time [1]. While this command is primarily for viewing deployment state and build logs, you can list deployments filtered by Git metadata—including githubCommitSha—using the vercel ls command [2]: vercel ls -m githubCommitSha= Vercel REST API To programmatically retrieve detailed metadata, including Git repository information, use the GET /deployments/{idOrUrl} endpoint [3][4]. When making this request, set the withGitRepoInfo query parameter to true to ensure the response includes the gitSource object, which contains the commit SHA, branch name, and repository metadata [3][4]. Environment Variables During the build and runtime of your deployment, Vercel automatically exposes the Git commit information as environment variables [5]: - VERCEL_GIT_COMMIT_SHA: The Git SHA of the commit that triggered the deployment [5]. - VERCEL_GIT_COMMIT_REF: The Git branch of the commit that triggered the deployment [5]. Custom Metadata If you are performing manual deployments via the CLI and need to associate Git information, you can use the --meta flag during the vercel deploy command [6]: vercel deploy -m githubDeployment=1 -m githubCommitSha= -m githubCommitRef= Note that for custom metadata to be recognized correctly, you must include the appropriate provider flag (e.g., githubDeployment=1, gitlabDeployment=1, or bitbucketDeployment=1) [6].
Citations:
- 1: https://vercel.com/docs/cli/inspect
- 2: https://vercel.com/docs/cli/list
- 3: https://vercel.com/docs/rest-api/deployments/get-a-deployment-by-id-or-url.md
- 4: https://vercel.com/docs/rest-api/sdk/deployments/get-a-deployment-by-id-or-url
- 5: https://vercel.com/docs/git/vercel-for-github
- 6: https://vercel.com/kb/guide/branch-variables-and-domains-not-linked-to-cli-deployments
🌐 Web query:
Vercel inspect output deployment metadata meta githubCommitSha githubCommitRef
💡 Result:
The Vercel deployment metadata fields githubCommitSha and githubCommitRef are part of a deployment's metadata object [1][2]. They are used to link a deployment to a specific Git commit and branch/reference, respectively [1]. Key details regarding these fields: 1. How they appear in metadata: These fields are typically stored within the meta object of a Vercel deployment, which is a key-value store of strings [3][2]. When you inspect a deployment, the meta object contains information such as: - githubCommitSha: The unique hash of the commit that triggered the deployment [4][2]. - githubCommitRef: The branch name or Git reference (e.g., main, feature/my-branch) associated with the deployment [1][2]. 2. How to access them: - Via Vercel CLI: While the standard vercel inspect command provides general deployment information (such as target, status, and URL), it may not display all metadata fields by default [5][6][7]. To retrieve full deployment details, including the meta object, you can use the Vercel REST API [8][3]. - Via REST API: You can retrieve deployment details by making a GET request to the /v11/deployments/{idOrUrl} or similar endpoints [8][3]. By setting the parameter withGitRepoInfo=true, the response includes a dedicated gitSource object that explicitly structures commit SHA, branch (ref), and repository metadata, which is often more reliable than parsing the meta object directly [3][9][2]. 3. How they are set: If you are performing deployments via the Vercel CLI and they are not automatically linked to Git, you can manually attach this metadata using the --meta or -m flag [1]: vercel deploy -m githubDeployment=1 -m githubCommitSha= -m githubCommitRef= Note that when using the --meta option, it is required to include a provider-specific flag (e.g., githubDeployment=1) to ensure the Git information is correctly associated with the deployment [1].
Citations:
- 1: https://vercel.com/kb/guide/branch-variables-and-domains-not-linked-to-cli-deployments
- 2: https://docs.sim.ai/integrations/vercel
- 3: https://vercel.com/docs/rest-api/sdk/deployments/get-a-deployment-by-id-or-url
- 4: https://github.com/vercel/vercel/blob/7e64cc27/packages/cli/src/commands/bisect/index.ts
- 5: https://github.com/vercel/vercel/blob/7e64cc27/packages/cli/src/commands/inspect/index.ts
- 6: https://vercel.com/docs/cli/inspect
- 7: https://github.com/vercel/vercel/blob/main/skills/vercel-cli/references/monitoring-and-debugging.md
- 8: https://vercel.com/docs/cli/list
- 9: https://examples.vercel.com/docs/rest-api/deployments/create-a-new-deployment.md
🌐 Web query:
Vercel deployments API githubCommitSha githubCommitRef deployment idOrUrl withGitRepoInfo
💡 Result:
The Vercel REST API provides mechanisms for interacting with deployments using Git metadata and retrieval options. 1. Creating a Deployment (POST /v13/deployments) When creating a new deployment, you can pass Git-related metadata within the request body to link the deployment to a specific commit [1][2]. This information is typically passed within the gitMetadata object, which includes fields such as [1][3]: - commitSha: The hash of the commit [1][3]. - commitRef: The branch on which the commit was made [1][3]. - commitMessage, commitAuthorName, commitAuthorEmail: Details about the commit author and content [1][3]. - ci, ciType, and other repository visibility settings [1][3]. 2. Retrieving a Deployment (GET /v13/deployments/{idOrUrl}) When retrieving a specific deployment using its ID or URL, you can request that Git repository information be included in the response by using the withGitRepoInfo query parameter [4][5]. - idOrUrl (Path Parameter): The unique identifier (e.g., dpl_...) or the hostname of the deployment [4]. - withGitRepoInfo (Query Parameter): A boolean-like string (true/false) that, when set to true, includes the gitSource object in the response. This object contains the commit SHA, branch name, and repository metadata [4][5]. The default value is false [4][5]. Example of the SDK usage for retrieval [2]: await vercel.deployments.getDeployment({ idOrUrl: "dpl_...", withGitRepoInfo: "true", });
Citations:
- 1: https://examples.vercel.com/docs/rest-api/sdk/deployments/create-a-new-deployment
- 2: https://github.com/vercel/sdk/blob/HEAD/docs/sdks/deployments/README.md
- 3: https://vercel.com/docs/rest-api/deployments/create-a-new-deployment
- 4: https://vercel.com/docs/rest-api/sdk/deployments/get-a-deployment-by-id-or-url
- 5: https://vercel.com/docs/rest-api/deployments/get-a-deployment-by-id-or-url
🌐 Web query:
sites:docs.vercel.com deployments githubCommitSha meta githubCommitRef
💡 Result:
On the Vercel platform, githubCommitSha and githubCommitRef are fields commonly found within the meta object of a deployment resource [1][2][3]. These fields serve the following purposes: githubCommitSha: Represents the unique identifier (hash) of the Git commit associated with a deployment [1][2][3]. githubCommitRef: Represents the Git branch or reference (e.g., main, develop) from which the deployment was triggered [1][2][3]. These metadata fields are automatically populated when a project is connected to a Git provider (such as GitHub, GitLab, or Bitbucket) and deployments are triggered via Git events [4]. When deploying manually via the Vercel CLI, this information may not be automatically linked; however, you can manually include these values in the deployment metadata using the --meta flag (or -m) [5]. When using the --meta flag, you must also include a provider-specific marker (e.g., githubDeployment="1") to ensure the platform correctly associates the metadata [5]. In the Vercel REST API, you can filter deployments by these metadata fields [4][6]. Although some API endpoints may not explicitly list meta properties as top-level query parameters in documentation, they can often be filtered using the meta- prefix [4]. For example, you can filter by commit SHA using meta-githubCommitSha= [4]. Additionally, when retrieving specific deployment details via the API, the meta object is included in the response payload, providing access to these commit-related details [2][7].
Citations:
- 1: https://docs.sim.ai/integrations/vercel
- 2: https://www.hookbase.app/docs/receive/integrations/vercel
- 3: https://docs.steelengine.com/tools/vercel
- 4: Add `meta` as a query param of REST API `/v6/deployments`, like CLI `list` vercel/vercel#8416
- 5: https://vercel.com/kb/guide/branch-variables-and-domains-not-linked-to-cli-deployments
- 6: How to find deployment by git commit hash using Vercel API? vercel/vercel#5301
- 7: https://vercel.com/docs/rest-api/sdk/deployments/get-a-deployment-by-id-or-url
🌐 Web query:
Vercel CLI inspect command prints meta githubCommitSha deployments
💡 Result:
The vercel inspect command is designed to retrieve and display information about a specific Vercel deployment, including its build status, environment, and associated metadata [1][2]. When a deployment is triggered via a Git-connected repository, vercel inspect typically displays the associated Git commit information—such as the commit SHA and message—within the command output [3][4]. While the inspect command does not have a dedicated flag specifically to "print" the githubCommitSha field in isolation, it inherently includes this metadata when it is present in the deployment's records [5][3]. Key points regarding Git metadata and Vercel CLI: - Inspection: When you run vercel inspect <deployment-url>, the output provides a summary of the deployment that includes the commit SHA associated with it [3][4]. - Filtering by Commit: If you are looking to find deployments that match a specific Git commit SHA, you should use the vercel list (or vercel ls) command with the --meta (or -m) flag to filter results [6]. For example: vercel ls -m githubCommitSha= [6] - Manual Metadata: If you are deploying via the CLI manually (e.g., from a CI/CD pipeline) and want to ensure this metadata is available for inspection, you can pass it during deployment using the -m flag (e.g., -m githubCommitSha=<sha>), which makes it searchable and visible in the Vercel dashboard and inspection tools [6][7]. If you are not seeing the commit SHA in your inspection output, ensure that the deployment was successfully linked to the repository metadata, or consider that the CLI sometimes relies on automated collection which can occasionally fail if Git environment conditions are not met [8].
Citations:
- 1: https://vercel.com/docs/cli/inspect
- 2: https://vercel.com/docs/cli
- 3: https://github.com/vercel/vercel-plugin/blob/main/commands/deploy.md
- 4: https://vercel.com/docs/observability/debug-production-errors
- 5: https://github.com/vercel/vercel/blob/7e64cc27/packages/cli/src/commands/bisect/index.ts
- 6: https://vercel.com/docs/cli/list
- 7: https://community.vercel.com/t/github-deployments-not-updated-when-using-vercel-cli-with-github-meta/29086
- 8: CLI deploy (
vercel --prod) no longer includes Git commit metadata vercel/vercel#15577
🌐 Web query:
"v13/deployments" "githubCommitSha" "githubCommitRef" meta
💡 Result:
The Vercel REST API endpoint POST /v13/deployments allows you to create a new deployment [1][2][3]. While githubCommitSha and githubCommitRef are commonly used fields, they are typically passed within the meta object or associated with the gitSource configuration, depending on whether you are creating a Git-backed or a file-based deployment [4][5][2]. The meta object is a flexible dictionary used to attach arbitrary key-value pairs (metadata) to a deployment [4][6]. When working with Git providers, developers often include specific keys such as: - meta.githubCommitSha: The hash of the commit [4][5]. - meta.githubCommitRef: The branch or reference name of the commit [4][5]. - meta.githubDeployment: A flag (often set to "1") to indicate the deployment source [5]. For Git-linked deployments, Vercel also provides a dedicated gitSource object in the request body, which explicitly defines the source repository and is the preferred method for automated deployments [4][1][2]. The gitSource object includes structured fields such as type (e.g., "github"), ref (the branch), repoId, and sha [1][7][2]. If you are using the Vercel CLI or manual REST calls to pass custom metadata without a formal Git integration, you can use the meta object to include these fields for tracking purposes [5][2]. Top results: [4], [5], [2]
Citations:
- 1: https://www.simworkflow.com/integration-operation/vercel-v13-deployments-post-f5c
- 2: https://github.com/vercel-labs/emulate/blob/main/skills/vercel/SKILL.md
- 3: https://vercel.rest/
- 4: https://examples.vercel.com/docs/rest-api/deployments/create-a-new-deployment.md
- 5: https://vercel.com/kb/guide/branch-variables-and-domains-not-linked-to-cli-deployments
- 6: https://vercel.com/docs/rest-api/deployments/get-a-deployment-by-id-or-url.md
- 7: https://github.com/theholocron/clients/blob/main/packages/vercel-client/src/deployments/deployments.ts
Compare production with remote main by full commit SHA.
git log main -1 depends on the local branch and does not reliably give the value to compare against deployment metadata. Use one of Vercel’s deployment inspection APIs, make sure withGitRepoInfo or equivalent metadata is included, fetch origin/main, and compare meta.githubCommitSha to git rev-parse origin/main. If meta.githubCommitSha is missing, mark the deployment as unverifiable.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/DEPLOYMENT.md` around lines 32 - 36, Update the production comparison
instructions in DEPLOYMENT.md to use a Vercel deployment inspection API with git
repository metadata enabled, fetch origin/main, and compare meta.githubCommitSha
against git rev-parse origin/main. State that missing meta.githubCommitSha makes
the deployment unverifiable, rather than relying on the local main branch or
commit reference.
Summary
docs/DEPLOYMENT.md, a short runbook covering the Vercel project setup,mainbranch protection, how to trigger a production redeploy, and a note on production potentially drifting frommainHEAD.Test plan
Generated by Claude Code
Summary by CodeRabbit