Vercel + GitHub Org Project Workflow

How BI & IT provisions projects in the GitHub org, connects them to Vercel, and how developers push changes from VS Code.

How a project goes from "new repo in the organization" to "deploying on Vercel," and how developers push their day-to-day changes. The one-time platform setup lives in Connecting a GitHub Organization to Vercel; this page covers the repeatable workflow on top of it.

The model

BI & IT provisions repos. Member repository creation is disabled org-wide; the BI & IT provisioners are Organization Owners, who can always create repos.
The creator owns the repo. Org base permission is None, so nobody has access to a repo unless explicitly added. The person who creates a repo is its admin.
IT connects Vercel centrally. Each new repo is imported into Vercel by IT, and the developer is added to the Vercel team so their commits deploy.

On a private repo connected to a Pro team, a commit only deploys if its author is a member of the Vercel team with their GitHub account linked. Granting GitHub access alone is not enough.

Provisioning a new project (BI & IT)

Create the repo from the template

Create the repository in the organization from the vercel-project-template (via Use this template on GitHub, or the Provision-OrgProject.ps1 script). The creator becomes the repo admin.

Grant the developer push access

Repo → Settings → Collaborators and teams → add the developer with the Write role. Skip if the creator is also the sole developer.

Import the repo into Vercel

In Vercel: Add New → Project → select the repo → confirm framework and root directory → Deploy.

Add the developer to the Vercel team

Invite the developer to the Vercel team and have them link GitHub under Account Settings → Login Connections. Without this, their pushes land in GitHub with no deployment.

(Optional) Protect `main`

Repo → Settings → Branches → require a pull request before merging, so production deploys are deliberate merges rather than accidental direct pushes.

Pushing changes from VS Code (developers)

Once you have admin or Write access to the org repo, this is the everyday loop.

Get the repo locally

If you haven't cloned it yet, in VS Code open the Command Palette (Ctrl+Shift+P) → Git: Clone → paste the repo URL (https://github.com/<org>/<repo>.git) → choose a local folder.

If you already have local code that isn't yet linked to the remote, add it instead:

git init
git remote add origin https://github.com/<org>/<repo>.git
git branch -M main

Set your commit identity

Your commit email must match a verified email on your GitHub account, or Vercel can't associate the commit with you and the deploy is skipped.

git config user.name  "Your Name"
git config user.email "you@company.com"

Work on a branch

git checkout -b feature/my-change

A branch keeps your work off main and produces a preview deployment when pushed.

Stage, commit, push

In the Source Control panel (Ctrl+Shift+G): stage your changes (+), type a commit message, and commit (✓). Then push with the Sync / Push button in the status bar, or:

git push -u origin feature/my-change

The first push triggers authentication. On Windows, Git Credential Manager opens a browser to sign in to GitHub — approve it once and it's cached. Alternatively, sign in first via the Accounts icon (bottom-left of VS Code) with your work account, and VS Code will reuse that for GitHub operations.

Open a PR and merge

Push the branch, open a pull request on GitHub, and check the Vercel bot's comment for the preview URL. When the change is approved, merge into main to trigger the production deployment.

Merge with Create a merge commit, not squash or rebase. Vercel builds based on the commit author: a merge commit is authored by whoever merges (so a deploying team member's merge deploys), but squash and rebase keep the original PR author on the commit. If that author isn't a deploying Vercel seat, the production deploy is blocked with "Git author must have access." Enforce this in repo Settings → Pull Requests: allow merge commits, disable squash and rebase.

If your organization enforces SAML SSO and a push is rejected even though you have access, your credential isn't authorized for the org. Authorize it: for a browser/OAuth sign-in, re-run the sign-in and approve SSO; for a Personal Access Token, authorize the token for the org under GitHub → Settings → Developer settings → Personal access tokens → Configure SSO.

Guaranteeing production deploys

Two ways to make "merge to main always deploys" reliable, from simplest to bulletproof:

Restrict the merge method (settings only). In repo Settings → Pull Requests, allow only merge commits and disable squash and rebase, then require a PR into main via branch protection. Every merge is then authored by whoever clicks merge — reliable as long as that person is a deploying Vercel seat.
Deploy hook + workflow (author-agnostic). Add a Vercel Deploy Hook for the production branch (Vercel → Project Settings → Git → Deploy Hooks) and store its URL as the repo secret VERCEL_PRODUCTION_DEPLOY_HOOK. The Deploy Production workflow (.github/workflows/deploy-production.yml) fires the hook on every push to main, which builds regardless of commit author or merge method.

If you adopt the deploy-hook workflow, disable Git-based production deploys so main doesn't deploy twice. Add this to vercel.json:

{ "git": { "deploymentEnabled": { "main": false } } }

Preview branches still deploy through the Git integration; only production is driven by the hook.

Troubleshooting

Symptom	Likely cause	Fix
Push rejected, "not authorized" though you have access	SAML SSO credential not authorized for the org	Authorize your OAuth grant or PAT for the org
Push succeeds but no Vercel deployment	Commit author not on the Vercel team, or GitHub not linked	Add the author to the Vercel team; link GitHub in Account Settings
Deployment skipped, author not recognized	Local git email doesn't match a verified GitHub email	Fix `git config user.email` to a verified address
Merge to `main` didn't deploy to production	PR was squashed or rebased, leaving a non-deploying author on the commit	Merge with a merge commit; disable squash/rebase on the repo
Developer can't create the repo	Member repo creation is disabled (by design)	BI & IT (an Owner) provisions the repo instead
Branch protection step failed during provisioning	`main` didn't exist yet when the rule was applied	Re-run after the template contents are seeded

Vercel + GitHub Org Project Workflow

On this page