3 homepage: https://github.com/therootcompany/gitdeploy
5 gitdeploy receives git webhooks and runs build and deploy scripts.
8 To update or switch versions, run `webi gitdeploy@stable`.
12 > gitdeploy makes it easy to build and deploy static sites (or anything else)
22 To get set up, you'll want to copy the example scripts and dotenv:
25 # The example scripts are a good starting point
26 rsync -av examples/ scripts/
28 # Edit this (or delete it)
29 mv scripts/dotenv .env
33 gitdeploy run --listen :4483 --github-secret xxxxx --exec scripts/
36 When gitdeploy receives a webhook it runs `scripts/deploy.sh` with the following
37 environment variables set:
40 GIT_REPO_ID=github.com/my-org/my-project
42 GIT_CLONE_URL=https://github.com/my-org/my-project.git
45 GIT_REPO_NAME=my-project
49 GIT_DEPLOY_JOB_ID=xxxxxx
52 The example `deploy.sh` looks for `deploy.sh` in the directory matching your
53 repository's URL, like this:
55 - ./scripts/github.com/example/project/deploy.sh
57 ### How to create a build & deploy script
59 The deploy scripts should exist in your `scripts/` directory, named after the
63 scripts/github.com/YOUR_ORG/YOUR_PROJECT/deploy.sh
66 1. Create a directory that matches the `GIT_REPO_ID`:
68 mkdir -p scripts/github.com/YOUR_ORG/YOUR_PROJECT
70 2. Create a `deploy.sh` that builds and deploys your project:
75 # Put bash in strict mode or bad things will happen.
79 # maybe you do different things with different branches
80 # in this case we just ignore all branches except for master
81 if [[ "${GIT_REF_NAME}" != "master" ]]
83 echo "Nothing to do for ${GIT_REPO_ID}#${GIT_REF_NAME}"
87 # make a temporary directory for the build
88 my_tmp="$(mktemp -d -t "tmp.XXXXXXXXXX")"
89 git clone --depth=1 "${GIT_CLONE_URL}" -b "${GIT_REF_NAME}" "${my_tmp}/${GIT_REPO_NAME}"
91 pushd "${my_tmp}/${GIT_REPO_NAME}/"
92 echo "Deploying ${GIT_REPO_ID}#${GIT_REF_NAME} ..."
94 # run an example build process
98 # deploy to an example staging site
99 rsync -av ./ ~/srv/staging.example.com/public/
102 # clean up after the build
103 rm -rf "${my_tmp}/${GIT_REPO_NAME}/"
106 ### How to set up a webhook
108 1. Generate a 128-bit random string:
110 xxd -l16 -ps /dev/urandom
112 2. Create a new Web Hook on your git platform:
113 - Github: `https://github.com/YOUR_ORG/YOUR_REPO/settings/hooks/new`
114 - Gitea: `https://GIT_DOMAIN/YOUR_ORG/YOUR_REPO/settings/hooks/gitea/new`
115 - Webhook: `https://YOUR_DOMAIN/api/webhooks/gitea`
117 `https://bitbucket.org/YOUR_ORG/YOUR_REPO/admin/addon/admin/bitbucket-webhooks/bb-webhooks-repo-admin`
118 3. Set the content type to JSON.
119 4. Add the Webhook URL:
123 https://YOUR_DOMAIN/api/webhooks/github
126 https://YOUR_DOMAIN/api/webhooks/gitea
129 https://YOUR_DOMAIN/api/webhooks/bitbucket?access_token=YOUR_SECRET
132 ### How to use ENVs (and .env)
134 Most of the flags, such as `--port` and `--github-secret` can also be set as
135 ENVs. You can create a `.env` like this, for example:
140 GITHUB_SECRET=xxxxxxxxxxx
144 [examples/dotenv](https://git.rootprojects.org/root/gitdeploy/src/branch/master/examples/dotenv)
147 ### How to use Deploy Keys & Personal Access Tokens
150 [Git Credentials Cheat Sheet](https://coolaj86.com/articles/vanilla-devops-git-credentials-cheatsheet/)
151 at <https://coolaj86.com/articles/vanilla-devops-git-credentials-cheatsheet/>.
153 ### How to reverse Proxy with HTTPS (Let's Encrypt)
155 See the [Caddy (Web Server) Cheat Sheet](https://webinstall.dev/caddy).