Skip to content
Tutorials Center
My learning

Topics

Lesson 63 of 78 ยท GitHub and Platforms

Deploying with Git

Deploy from Git: push-to-deploy with a bare repo and post-receive hook, release folders with atomic symlinks, release branches and tags, and safe rollbacks with revert.

Sooner or later the code in your repository has to run somewhere other than your laptop. Git is a good deployment tool because it already answers the hard questions: which exact version is running (a commit hash), what changed since the last deploy (a diff), and how do I go back (point at an older commit). Heroku, Dokku, Vercel, Netlify and many other platforms deploy when you git push. Under the hood, they use the same pieces you can build yourself: a bare repository, a hook and a working directory.

In this lesson you will build a push-to-deploy setup with a post-receive hook, make deployments atomic with release folders and a symlink, choose between deploying a branch or a tag, and roll back without rewriting history. Everything runs locally in the sandbox; "the server" is just another folder.

Four ways to get code onto a server

Strategy How it works Good for Watch out for
Pull on the server SSH in and run git pull in the live folder tiny personal sites partially updated files, local edits, no easy rollback
Push-to-deploy git push production main triggers a hook that updates the live files small teams, simple apps the hook must be correct; builds on the server are slow
Release folders each deploy goes into releases/<id>, then a current symlink switches production servers needs a little more setup, and disk cleanup
CI/CD pipeline CI builds an artifact and a deploy job ships it larger teams (GitHub Actions, Jenkins) more moving parts

The first is risky because the working tree on the server is edited in place while visitors are using it. The others never expose a half-updated state if you design them carefully.

flowchart LR
  A["Developer<br/>git push production main"] --> B["Bare repo on server"]
  B --> C["post-receive hook"]
  C --> D["Check out files<br/>into a release folder"]
  D --> E["Switch 'current' symlink"]
  E --> F["Web server serves current/"]

Push-to-deploy: the push runs a hook that prepares a release and switches to it in one step.

Push-to-deploy with a bare repository

Create a bare repository on the server (see Remotes) and add a post-receive hook. Git runs it after a push is accepted, with one old new ref line per updated ref on standard input. The hook uses --work-tree to check the pushed branch out into the live folder.

Bash A first push-to-deploy hook

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.

The first push to main filled the site folder. The push of topic was acknowledged but did not touch the live files, because the hook only acts on refs/heads/main. The third push replaced the page with version 2. This is exactly what Dokku-style platforms automate. It has two weaknesses. checkout -f overwrites files one by one, so a visitor could briefly see a mix of old and new files. And files you delete from the repository are not removed from the live folder. Use release folders to fix both.

The hook runs as the server user. Anyone who can push to the repository can execute that hook's code path, so only give push access to people you trust with the server, and never put secrets in the repository.

Release folders and an atomic switch

The professional pattern, used by Capistrano, Deployer, Envoyer and homemade scripts alike, keeps every deployment in its own folder and exposes the live one through a symlink. Replacing a symlink is a single atomic filesystem operation, so visitors see either the old release or the new one, never a mix. Rolling back is pointing the symlink at an earlier folder.

TEXT
app/
  releases/
    2026-01-01-a1b2c3d/   <- older release, kept for rollback
    2026-01-02-e4f5a6b/   <- newest release
  current -> releases/2026-01-02-e4f5a6b
  shared/                 <- uploads, .env, logs (linked into each release)

The deploy script uses git archive to export the commit into the new folder with no .git directory (git bundle and git archive). It then runs your build steps and finally switches the link.

Bash Deploy a commit to a release folder, switch, then roll back

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.

Each deploy exported the tag into releases/<tag>, built a temporary link and renamed it over current (mv -T makes the rename atomic, while ln -sfn alone briefly removes the old link). Release 2 deleted legacy.txt, and because each release is a fresh folder the file is simply gone, which push-to-deploy with checkout -f would not have done. The rollback took one command and no Git at all. In real setups the script also links the shared/ folder, runs migrations, warms caches, health-checks the new release and only then switches the link; it keeps the last five releases and deletes older ones.

Which ref do you deploy?

You need a rule for which commit counts as "production". The common choices:

  • Deploy main continuously. Every merged pull request goes live (continuous deployment). Works with a strong test suite and feature flags. See Branch Workflows.
  • A production branch that you fast-forward from main when ready. The deploy hook watches this branch, and git log production..main shows what has not shipped yet.
  • Release branches such as release/2.1, cut from main, where only bug fixes land and are cherry-picked across. Use this when you support several versions at once.
  • Tags such as v2.1.0. A tag is immutable by convention, so "deploy v2.1.0" always means the same code, and the version number is visible in logs and error reports (Tags). The deploy hook can ignore branches entirely and react to refs/tags/v*.

Tags are the most auditable option. Let the deploy script record the identity of what it shipped, so you can ask production which version it is running:

Bash Stamp the deployed version and compare environments

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.

git describe yields v1.0-1-g... for a build one commit after the tag; the hash suffix makes any build traceable. The range production..main lists what the next deploy will ship. Because production is an ancestor of main, promoting it is a fast-forward, with no merge commit, and the list is empty afterwards.

Rolling back safely

Things go wrong, and the question is how to undo them quickly and without making it worse. In order of preference:

  1. Switch to the previous release (symlink or redeploy the previous tag). Instant, and no Git history changes. Fix the problem calmly afterwards.
  2. git revert the bad commits on main, and push. This adds new commits that undo the change, and the history shows what happened, as explained in Revert. Every collaborator pulls it normally.
  3. Hotfix branch: branch from the production tag, fix, tag v2.0.1, deploy, then merge the fix back to main so it is not lost.
  4. Never reset --hard and force-push a deployed branch unless the whole team agrees. It rewrites commits others have already pulled and breaks the audit trail (reset in Depth).

Database migrations are the real obstacle to rollbacks: code can go back instantly, but a dropped column cannot. Make migrations backward compatible (add first, remove later) so the old release still works with the new schema.

Safety checklist

  • Deploy from a known commit (tag or hash), never from a dirty working directory.
  • Keep configuration and secrets outside the repository, in shared/ or environment variables, and cover the repository with a proper .gitignore.
  • Run the tests first. A hook that deploys on push should be the last step after CI, not a replacement for it.
  • Make the deploy atomic and keep at least the previous release.
  • Log every deploy: who, which commit, when. A one-line append to a file or a message to a chat channel is enough.
  • Remember that hooks are scripts: they need error handling (set -e) so a failed build never switches the symlink.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. In a push-to-deploy setup, which hook does the work after a push is accepted?

    post-receive runs on the server after the refs were updated and receives the pushed refs on stdin; it can check files out into the live folder.
  2. 2. Why use release folders and a current symlink instead of checking out files directly into the live folder?

    A new release is prepared completely in its own folder; replacing the link is a single atomic rename. The previous release remains available for rollback.
  3. 3. What does git log --oneline production..main show?

    A..B lists commits reachable from B but not from A. With production as the deployed branch, that is the pending work.
  4. 4. A bad release is live. What is the safest first step?

    Going back to a known-good release is fast and rewrites no history. Fix the problem afterwards, for example with git revert.

Summary

  • Git identifies what runs in production: a commit hash or tag, the diff since the last deploy and an easy way back.
  • Push-to-deploy uses a bare repository plus a post-receive hook that checks out the pushed branch; it is simple but not atomic and does not remove deleted files.
  • Release folders with an atomically switched current symlink (use git archive to export) give clean, instantly reversible deployments.
  • Decide what counts as production: main, a production branch, release branches or tags; tags are the most auditable.
  • Roll back by switching releases first, then fix forward with git revert or a hotfix branch; avoid force-pushing deployed branches.
  • Keep secrets out of the repository, deploy only tested commits and log every deploy.

Next: Common Mistakes and How to Fix Them