gitdeploy receives git webhooks and runs build and deploy scripts.

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

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