You have a web project made with Claude. The useful handoff is a repository you control and a live site whose source, audience and later updates you can trace. This guide takes a suitable Claude Code project, or a usable web export from Claude Design, through GitHub and Vercel's Git integration. You will check the first production release, a later branch preview and the production deployment after an approved merge. The steps are based on current product documentation, checked on 21 October 2026; BIG CHANGE did not deploy a project for this guide.
The reader is the project owner or release lead who can approve source, repository access and the first production release. A designer's export, a GitHub push and a successful Vercel build each answer a different question. None alone proves the intended site is safe to serve. If you already have a working local dashboard and want a one-time CLI release, our first Vercel release guide covers that narrower path.
Before you start
You need Git, the GitHub CLI for the gh commands below, a GitHub account with permission to create or use the intended repository, and access to the intended Vercel team. Install the CLI using GitHub's instructions for your operating system, then run gh --version to confirm it is available and gh auth status --active --hostname github.com to check the active account and authentication. If either command fails, install or authenticate the CLI and repeat the checks before creating a repository. If the active account is wrong, switch or sign in to the authorized account and verify it again; never use --show-token in a release record. Decide who may see production and previews. Get approval for the first production deployment and for the policy under which future merges to the production branch may deploy automatically. If either release or its audience is undecided, keep the project local.
Identify OWNER/REPO before any repository command: OWNER is the exact authorized GitHub user or organization, and REPO is the new repository name. Do not type those placeholders literally. Record the intended Vercel team, plan, production branch (called main below), project name and domain. The commands below assume a new repository and a local project directory. If a repository or remote already exists, inspect and use its reviewed history instead of initializing, recreating or force-pushing it.
For a private GitHub organization repository, check deployment eligibility before import. Vercel's Git documentation says a Hobby team cannot deploy from one. For a private organization repository on Pro or Enterprise, the commit author needs a linked Vercel identity and access to the destination team; Hobby also restricts eligible commit authors. Check the actual team, GitHub connection and author account. Choose an authorized supported team or permitted personal repository if necessary; making sensitive source public is not a repair.
Repository visibility and site visibility are separate. If the site must be restricted, check the Vercel team's default Deployment Protection before creating the project, and verify the effective project setting and any exceptions before Deploy. All Deployments with Vercel Authentication is documented as available on all plans and covers production domains as well as generated URLs. Standard Protection leaves production domains open. Authentication may admit team members whose access is broader than your intended audience, so establish who can sign in and test an allowed and a denied viewer later. If you cannot establish protection for restricted content before import, stop before the first deployment. Application login and backend authorization may still be necessary for user data.
1. Get web files you can run
With Claude Code, work from the actual project directory. Find the app root, source, dependency file, lockfile and documented install, run, build and test commands. Ask the project owner to review the generated code and changes. A chat transcript or rendered preview is not a substitute for the files the build will consume.
With Claude Design or an Artifact, use its Export control to download a ZIP or standalone HTML where the project offers one. Claude's export guide also lists PDF, PPTX and other presentation outputs. Extract a ZIP into a private folder and inspect what it actually contains. A standalone HTML file may be a suitable static page; a ZIP may contain assets or a runnable project. Neither format promises working navigation, a backend or Vercel compatibility. If you only have a presentation, image, missing assets or a demo whose required behavior cannot run locally, return to source creation before starting this release.
Write down the source directory and an identifying local file hash if useful, plus the app's real entry point and route list. Check rights to images, fonts and other included material. Inspect dependencies and data calls. Remove test credentials, personal data and any generated content that the owner has not approved to publish.
2. Build and review locally
Run the project's own install, build and tests from its actual root. For a Node project whose lockfile uses npm, the sequence may be:
npm ci
npm run build
npm testUse the scripts in that project's package.json; npm test is only applicable when the project defines it. For standalone HTML, open the local file or serve it with an approved local server and check links and assets. For either path, visit representative routes at desktop and phone widths, exercise a real form or data path with permitted test data, and inspect browser and server errors. Record what passed, what failed and what was not exercised. A local build only tests this local configuration.
List variables the app needs, separating build-time, server-side and browser-exposed values. Put secret values in the authorized Vercel environment settings for the right Production or Preview target, never in a repository, front-end bundle or example command. Check whether a service needs its own staging endpoint for preview. Confirm current build settings: framework preset, root directory, install/build command and output directory depend on this source. Do not guess the output folder from another project.
3. Review and push the intended GitHub source
Prepare a project-specific .gitignore for local environment files, credentials, node_modules, build output and private data. Review the whole directory, including generated files and license terms. A secret scanner can help, but inspect the staged diff yourself. In a new, unversioned project, these commands establish an explicit main branch and show what will be committed:
git init -b main
git status --short
git add -- README.md package.json package-lock.json src public .gitignore
git diff --cached --stat
git diff --cached
git commit -m "Review initial web project"
git rev-parse HEADReplace the git add paths with the exact reviewed files and directories in your project. A standalone HTML export needs its own reviewed paths, not this Node example. Inspect git diff --cached for keys, personal data, unexpected generated content and files that should remain local before committing. Check the Git commit author identity too; it matters for private-repository deployment eligibility. If a secret was committed, stop and follow the owner's credential rotation and history-remediation process before pushing. Merely adding it to .gitignore afterward does not erase the commit.
Check which GitHub account is active and confirm that OWNER/REPO is the approved destination. For a new private repository from this local directory, GitHub CLI documents this explicit source and push path:
gh auth status
gh repo create OWNER/REPO --private --source=. --remote=origin --push
gh repo view OWNER/REPO
git remote -v
git rev-parse HEADThe create command can create and push without another prompt. Do not run it until the destination, visibility and commit have been approved. If origin already exists or the repository was made in GitHub first, inspect its URL and default branch and use the normal reviewed push procedure for that repository. Read back the actual GitHub owner, visibility, branch, commit and files in the web view. A private repository controls source access; it does not restrict the deployed URL.
4. Treat Vercel import as the first production release
In Vercel, choose the intended team, Add New → Project, and import the exact GitHub repository. Confirm the GitHub integration can see that repository. Before selecting Deploy, check the team and plan, connected repo, production branch, framework preset, root, build/output settings, environment-variable names and targets, domain plan and effective Deployment Protection. Read back team defaults and project overrides or exceptions; the current protection documentation explains why a preview-only setting cannot establish production privacy. Keep variable values out of release notes and screenshots.
Have the owner approve this specific initial release and its audience. Selecting Deploy starts the first build and may put production content at a generated Vercel URL even before a custom domain is assigned. Record the project, deployment ID, URL, domain if configured, production branch and source commit. If import is blocked by the private-repository plan or author rule, return to the eligibility decision; do not expose the source to bypass it.
When the build finishes, inspect its build log and the commit shown in Vercel. Compare that SHA to the reviewed GitHub SHA. Load the production domain and generated deployment URL. Check the home page, at least one deep route and a real API or data route if the app has one. Check the approved content/version and errors. For restricted content, test an intended signed-in viewer and a signed-out or explicitly denied viewer on relevant routes and URLs. Record actual results; a green build badge does not prove access or function.
5. Prove a branch preview
Make one identifiable, approved change on a non-production branch. The branch name below is an example; use your team's naming rule. Run the local checks again, inspect the diff, commit and push:
git switch -c check-preview
git status --short
git add -- src
git diff --cached
git commit -m "Check preview update"
git rev-parse HEAD
git push -u origin check-previewReplace src with the exact reviewed changed paths. Open a GitHub pull request into the configured production branch. Vercel's GitHub integration guide documents preview deployments for pushes and pull requests. Read the preview deployment ID, URL, branch and source SHA; compare them to the branch commit. Check changed content, routes, browser and runtime errors, Preview variable targets and intended/denied viewers at the preview URL. A preview may use different data or credentials from production, so exercise its critical path with permitted test data. A PR comment or link alone is not a test result.
6. Approve the merge and check the next production deployment
Review the PR's source diff, checks and preview observations. Obtain the production approval required by your team before merging. A merge or direct push to Vercel's configured production branch can automatically create the next production deployment, so the merge is a release action. Avoid using the branch preview as an implicit approval.
After the authorized merge, read GitHub's production-branch SHA and Vercel's new production deployment ID, status and source commit. Compare the exact identities; the merge commit may differ from the preview branch commit. Visit the production domain and generated URL again. Recheck the changed behavior, deep and data routes, build and runtime logs, Production variable targets, allowed viewer and denied viewer. Record the old and new deployment IDs and which commit each served. The task is complete only when the intended repo and both production releases and the intervening preview have matching source readbacks and the audience checks pass.
If a check fails
A build error belongs to the exact failed deployment: inspect its log, compare local build settings, then correct the source or project configuration under the normal review policy. A 404 on a deep route may be an output or routing configuration issue; an API error may involve a missing Production or Preview variable, backend access or an app bug. Inspect variable names and targets, then make a new reviewed deployment after fixing them. Never paste secret values into a ticket or log.
If a push or deploy response is uncertain, read the GitHub branch SHA and Vercel deployment list before retrying. If the wrong repo, team or branch is selected before the first Deploy, stop and correct it. If a URL exposes restricted data, use authorized protection controls and verify denial, rotate any exposed credential and follow the owner's incident process; rolling back a deployment cannot retract what was already seen.
Review current Vercel plan limits, usage and any paid protection, domain or connected service before approving release. Build and runtime usage may incur charges. This guide has no measured elapsed time, bill, build result or viewer result for your account. Keep a private release record of the local checks, reviewed file list, source SHAs, repository visibility, Vercel project settings, deployment IDs, URLs, route observations, audience tests and unresolved issues.
The big change
- A Claude-made web project becomes maintainable source when its actual runnable files, rights, dependencies and secrets have been reviewed and committed to the intended GitHub repository.
- Vercel's first Git import is a production decision; branch previews and later production merges need their own commit, route and audience checks.
- The proof is the reader's linked GitHub and Vercel readback across the first release, preview and approved update, not a successful export or build notification.
