Playbook
Home / Vercel & Deploy / Deploy

Deploy a GitHub repo to Vercel for the first time

safe beginner #vercel#deploy#import#first deploy#astro

When to use this: Your code is on GitHub and you want it live on a *.vercel.app URL that redeploys on every push.

Before you start

Steps

  1. Start a new project

    In the Vercel dashboard click 'Add New...' then 'Project'. Under 'Import Git Repository' choose GitHub.

  2. Authorise the GitHub app

    If your repo is not listed, click 'Adjust GitHub App Permissions' and give Vercel access to this repo (or all repos). Then click 'Import' next to it.

  3. Check the detected settings

    Vercel detects the framework (Astro for this site). Defaults: build command npm run build, output directory dist (Astro), install command npm install. Leave them unless something is wrong. Add environment variables now if the site needs them.

  4. Deploy

    Click 'Deploy'. The first build takes about a minute, then you get a URL like my-site.vercel.app.

  5. From now on, deploys happen on push

    terminal
    git add -A
git commit -m "Update content"
git push

    Pushing to main creates a Production deployment. Pushing any other branch creates a Preview deployment.

How to verify it worked

  • The project's Deployments tab shows a green 'Ready' deployment and the URL opens your site.

How to undo it

To unlink: Project, Settings, Git, 'Disconnect'. To delete the whole project: Settings, scroll to 'Delete Project'. Your GitHub repo is not affected.

Common errors and fixes

Build fails: Command "npm run build" exited with 1 Open the failed deployment's build log (see the build-log scenario). Reproduce locally with npm run build.
Repository is not in the import list The Vercel GitHub app lacks access. Use 'Adjust GitHub App Permissions' and add the repo.
Site deploys but shows 404 The output directory is wrong. For Astro it is dist; for Next.js leave it empty. Check Settings, Build and Deployment.

Q&A

Do I need a vercel.json?

Not for a standard Astro, Next.js or Vite project. Vercel detects the framework. Add vercel.json only for redirects, headers, or custom build settings.

Does Vercel read my code from my PC?

No. It builds from GitHub, so only what you pushed is deployed.

Practice these as flashcards →

Terms in this scenario

Production deploymentBuildmain

Related scenarios

My notes

Saved in this browser only.