Vercel Hobby is fine as long as you are the only person pushing. Once someone else commits to a private repo connected to a Hobby project, Vercel refuses to deploy that commit and points you to Pro. It checks the Git author of the commit, and the author has to be you, the account owner.

My setup: a private repo where more than one person commits, and a small side project on Hobby. I don't want to pay for seats on something this small, so I put a mirror repo in between.

The idea

Use two repos:

  1. Source repo: private. Everyone works here.
  2. Deploy repo: private and owned by the same GitHub account as Vercel. Vercel is connected only to this repo.

A GitHub Actions workflow in the source repo copies the code into the deploy repo on every push to main. The commit in the deploy repo is authored by the Vercel account owner, so Vercel sees one author and deploys it.

The token: only one permission

The default GITHUB_TOKEN can't push to a different repo, so you need a personal access token from the account that owns the deploy repo.

I first assumed this needed a pile of scopes. It doesn't. Create a fine-grained token:

  • Repository access: Only select repositories, then pick the deploy repo.
  • Repository permissions: Contents: Read and write.

That's it. GitHub adds Metadata: Read-only automatically. You don't need Workflows, because the workflow deletes .github/ before pushing, so no workflow files ever land in the deploy repo. You don't need Administration or Pull requests either.

Save it in the source repo as an Actions secret called DEPLOY_REPO_TOKEN.

Version 1: one commit, force push

This is what I started with. Each run throws away the old history and pushes a single fresh commit:

name: Sync to deploy repo
on:
  push:
    branches: [main]

jobs:
  sync:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Push snapshot as single commit
        env:
          TOKEN: ${{ secrets.DEPLOY_REPO_TOKEN }}
        run: |
          rm -rf .git .github
          git init -b main
          git config user.name "your-username"
          git config user.email "you@example.com"
          git add -A
          git commit -m "Deploy ${GITHUB_SHA::7}"
          git push --force https://x-access-token:${TOKEN}@github.com/your-username/deploy-repo.git main

It works, but I didn't like two things about it:

  • The username and email are hardcoded, and the email is committed to a public workflow file in plain text.
  • --force wipes the deploy repo's history every time, so the deploy repo only ever has one commit. Vercel's deployment list still works, but you can't look at what changed between deploys from the deploy repo itself.

Fix 1: get the identity from the token

The token already belongs to the deploy account, so ask GitHub who that is. gh is preinstalled on ubuntu-latest, and GET /user works with a fine-grained token without any extra permission:

LOGIN=$(gh api user --jq .login)
ID=$(gh api user --jq .id)
git config user.name "$LOGIN"
git config user.email "${ID}+${LOGIN}@users.noreply.github.com"

The ID+login@users.noreply.github.com address is GitHub's private noreply email for that account. GitHub links commits made with it to the account, and Vercel treats them as yours too, with no real email in the YAML. If you swap the token for a different account later, the identity changes with it.

Fix 2: keep history, no force push

Clone the deploy repo instead of starting a new one each time, replace its files with the latest source, and add a normal commit on top. Older deploy commits stay, and you can git diff between any two of them.

The token only needs Contents: Read and write for this too. Cloning is a read, and a normal push is a write.

name: Sync to deploy repo
on:
  push:
    branches: [main]

concurrency:
  group: deploy-sync
  cancel-in-progress: false

jobs:
  sync:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          path: src

      - name: Push to deploy repo
        env:
          TOKEN: ${{ secrets.DEPLOY_REPO_TOKEN }}
          GH_TOKEN: ${{ secrets.DEPLOY_REPO_TOKEN }}
          DEPLOY_REPO: deploy-repo
        run: |
          LOGIN=$(gh api user --jq .login)
          ID=$(gh api user --jq .id)

          git clone --depth 1 \
            "https://x-access-token:${TOKEN}@github.com/${LOGIN}/${DEPLOY_REPO}.git" deploy

          rsync -a --delete \
            --exclude .git --exclude .github \
            src/ deploy/

          cd deploy
          git config user.name "$LOGIN"
          git config user.email "${ID}+${LOGIN}@users.noreply.github.com"

          git add -A
          if git diff --cached --quiet; then
            echo "Nothing changed, skipping"
            exit 0
          fi

          MSG=$(git -C ../src log -1 --format=%s)
          git commit -m "Deploy ${GITHUB_SHA::7}: ${MSG}"
          git push origin HEAD

What each part does:

  • path: src checks out the source into its own folder, so it never touches the deploy clone.
  • rsync --delete makes the deploy repo match the source exactly, so files deleted in the source are deleted in the deploy repo too. It skips .git (so the deploy repo keeps its own history) and .github (so no Workflows permission is needed).
  • git diff --cached --quiet skips the commit when nothing changed, for example after a push that only touched .github/. No empty commit, no wasted Vercel build.
  • The commit message includes the short source SHA and the source commit's subject, so every deploy commit points back to the real change.
  • concurrency runs syncs one at a time. Without it, two quick pushes to main can race, and the second git push gets rejected because it's behind.
  • --depth 1 keeps the clone fast. A normal push from a shallow clone works fine as long as nothing else writes to the deploy repo.

If the deploy repo is brand new and empty, push one initial commit to it by hand first, because git clone of an empty repo gives you no branch to push to.

Don't add Co-authored-by

It's tempting to credit the real author with a Co-authored-by: trailer in the deploy commit. Don't. The whole point is that the deploy repo has one author. Put credit in the commit message as plain text if you want it, or just rely on the source SHA.

Vercel side

  • Connect the Vercel project to the deploy repo, not the source repo.
  • If the source repo was connected before, disconnect it, otherwise Vercel will keep trying (and failing) to build collaborator commits there too.
  • Environment variables stay in the Vercel project as before. Nothing about them changes.

A fair note

Vercel's Hobby plan is meant for personal, non-commercial use. This setup is fine for a side project where a friend sends you a few commits. If it's a team shipping a commercial product, Pro is the plan that actually fits, and it also gets you preview deployments per contributor, which this mirror setup loses.