Skip to content

docs: add Vercel deployment/redeploy runbook #53

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
projectamazonph merged 1 commit into from
Aug 2, 2026
Merged

docs: add Vercel deployment/redeploy runbook #53

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
36 changes: 36 additions & 0 deletions docs/DEPLOYMENT.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,36 @@
# Deployment (Vercel)

## Project

- Vercel project: `amazon-ad-console` (team: `ryandabao1982s-projects`)
- Framework: Next.js, built with Turbopack
- Git integration: GitHub `projectamazonph/Amazon-ad-console`, production tracks the `main` branch
- No custom domain configured — production is served on `*.vercel.app` aliases only

## Branch protection

`main` requires a pull request and a passing `Type-check, test, build` status check.
Direct pushes to `main` (including empty/no-op commits) are rejected by GitHub rules —
all changes, including deploy-trigger commits, must go through a PR.

## Triggering a redeploy

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:
Comment on lines +18 to +19

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**
Comment on lines +21 to +23

@coderabbitai coderabbitai Bot Aug 2, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🎯 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' || true

Repository: 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:

🏁 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' || true

Repository: 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.

Suggested change
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.


This re-runs the build for that exact deployment's commit without needing a new push.

To deploy a *different* commit to production instead, merge a PR into `main` — the
GitHub integration builds and promotes it automatically once CI passes.

## Known gotcha: production can drift from `main`

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`.
Comment on lines +32 to +36

@coderabbitai coderabbitai Bot Aug 2, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🎯 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})
PY

Repository: 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:

🌐 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:

🌐 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:

🌐 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:

🌐 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:

🌐 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:

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.

Loading