Playbook
Home / Git & GitHub / Branches

Branch, pull request, preview, merge (safest flow for a live site)

safe intermediate #pull request#pr#preview#workflow#vercel

When to use this: You want to change the live site without risking it: test on a Vercel preview and merge only when happy.

Before you start

Steps

  1. Start a branch

    terminal
    git switch -c my-change

    All edits go on this branch, never on main.

  2. Commit and push the branch

    terminal
    git add -A
git commit -m "Describe the change"
git push -u origin my-change

    Vercel builds a preview deployment for the branch and posts its URL.

  3. Open a pull request

    terminal
    gh pr create --fill

    --fill uses your commit messages for the title and body. Or use the 'Compare & pull request' button on GitHub. Vercel comments on the PR with the preview link.

  4. Check the preview

    Open the preview URL from the PR comment and test it. If something is wrong, commit more fixes to the same branch and push; the preview updates.

  5. Merge

    terminal
    gh pr merge --squash --delete-branch

    Merges into main (squash = one tidy commit) and deletes the branch. You can click 'Merge pull request' on GitHub instead. The merge triggers the production deploy.

  6. Update your local main

    terminal
    git switch main
git pull
git fetch --prune

    Brings the merge to your PC and cleans up the branch pointers GitHub deleted.

How to verify it worked

  • The PR shows 'Merged', and Vercel lists a successful Production deployment for main.

How to undo it

Revert the merged PR on GitHub (button 'Revert' on the PR page) or locally: git revert <merge-or-squash-commit-id> and push.

Common errors and fixes

Preview build fails but works locally Open the deployment's build log in Vercel (see the build-log scenario). Often a missing environment variable or a filename case mismatch.
gh: command not found Install the GitHub CLI, or do the PR steps in the browser.

Q&A

Why is the PR flow better than pushing to main?

Every PR gets its own preview URL, so you test the real build before it reaches production.

Squash, merge commit or rebase when merging the PR?

Squash gives one clean commit per PR and is a good default for a solo site. Merge commit keeps every commit. Rebase merge keeps them in a straight line.

Practice these as flashcards →

Terms in this scenario

Pull request (PR)Preview deploymentProduction deploymentBranch

Related scenarios

My notes

Saved in this browser only.