gitdeploy receives git webhooks and runs build and deploy scripts.

To update or switch versions, run webi gitdeploy@stable.


These are the files / directories that are created and/or modified with this install:


Cheat Sheet

gitdeploy makes it easy to build and deploy static sites (or anything else) from git webhooks.

Works with

  • GitHub
  • Gitea
  • Bitbucket
  • and more ...

To get set up, you'll want to copy the example scripts and dotenv:

# The example scripts are a good starting point
rsync -av examples/ scripts/

# Edit this (or delete it)
mv scripts/dotenv .env
gitdeploy run --listen :4483 --github-secret xxxxx --exec scripts/

When gitdeploy receives a webhook it runs scripts/ with the following environment variables set:




The example looks for in the directory matching your repository's URL, like this:

  • ./scripts/

How to create a build & deploy script

The deploy scripts should exist in your scripts/ directory, named after the repo's name.

  1. Create a directory that matches the GIT_REPO_ID:

    mkdir -p scripts/
  2. Create a that builds and deploys your project:

    # Put bash in strict mode or bad things will happen.
    set -u
    set -e
    # maybe you do different things with different branches
    # in this case we just ignore all branches except for master
    if [[ "${GIT_REF_NAME}" != "master" ]]
        echo "Nothing to do for ${GIT_REPO_ID}#${GIT_REF_NAME}"
        exit 0
    # make a temporary directory for the build
    my_tmp="$(mktemp -d -t "tmp.XXXXXXXXXX")"
    git clone --depth=1 "${GIT_CLONE_URL}" -b "${GIT_REF_NAME}" "${my_tmp}/${GIT_REPO_NAME}"
    pushd "${my_tmp}/${GIT_REPO_NAME}/"
        echo "Deploying ${GIT_REPO_ID}#${GIT_REF_NAME} ..."
        # run an example build process
        npm ci
        npm run build
        # deploy to an example staging site
        rsync -av ./ ~/srv/
    # clean up after the build
    rm -rf "${my_tmp}/${GIT_REPO_NAME}/"

How to set up a webhook

  1. Generate a 128-bit random string:

    xxd -l16 -ps /dev/urandom
  2. Create a new Web Hook on your git platform:

    • Github:
    • Gitea: https://GIT_DOMAIN/YOUR_ORG/YOUR_REPO/settings/hooks/gitea/new
      • Webhook: https://YOUR_DOMAIN/api/webhooks/gitea
    • BitBucket:
  3. Set the content type to JSON.

  4. Add the Webhook URL:

    # Github
    # Gitea
    # Bitbucket

How to use ENVs (and .env)

Most of the flags, such as --port and --github-secret can also be set as ENVs. You can create a .env like this, for example:



See the examples/dotenv for more info.

How to use Deploy Keys & Personal Access Tokens

See the Git Credentials Cheat Sheet at

How to reverse Proxy with HTTPS (Let's Encrypt)

See the Caddy (Web Server) Cheat Sheet.


Report an Issue Submit Installer Star on GitHub