gitdeploy/README.md

   1 ---
   2 title: gitdeploy
   3 homepage: https://github.com/therootcompany/gitdeploy
   4 tagline: |
   5   gitdeploy receives git webhooks and runs build and deploy scripts.
   6 ---
   7
   8 To update or switch versions, run `webi gitdeploy@stable`.
   9
  10 ## Cheat Sheet
  11
  12 > gitdeploy makes it easy to build and deploy static sites (or anything else)
  13 > from git webhooks.
  14
  15 Works with
  16
  17 - GitHub
  18 - Gitea
  19 - Bitbucket
  20 - and more ...
  21
  22 To get set up, you'll want to copy the example scripts and dotenv:
  23
  24 ```bash
  25 # The example scripts are a good starting point
  26 rsync -av examples/ scripts/
  27
  28 # Edit this (or delete it)
  29 mv scripts/dotenv .env
  30 ```
  31
  32 ```bash
  33 gitdeploy run --listen :4483 --github-secret xxxxx --exec scripts/
  34 ```
  35
  36 When gitdeploy receives a webhook it runs `scripts/deploy.sh` with the following
  37 environment variables set:
  38
  39 ```bash
  40 GIT_REPO_ID=github.com/my-org/my-project
  41
  42 GIT_CLONE_URL=https://github.com/my-org/my-project.git
  43
  44 GIT_REPO_OWNER=my-org
  45 GIT_REPO_NAME=my-project
  46 GIT_REF_TYPE=branch
  47 GIT_REF_NAME=master
  48
  49 GIT_DEPLOY_JOB_ID=xxxxxx
  50 ```
  51
  52 The example `deploy.sh` looks for `deploy.sh` in the directory matching your
  53 repository's URL, like this:
  54
  55 - ./scripts/github.com/example/project/deploy.sh
  56
  57 ### How to create a build & deploy script
  58
  59 The deploy scripts should exist in your `scripts/` directory, named after the
  60 repo's name.
  61
  62 ```txt
  63 scripts/github.com/YOUR_ORG/YOUR_PROJECT/deploy.sh
  64 ```
  65
  66 1. Create a directory that matches the `GIT_REPO_ID`:
  67    ```bash
  68    mkdir -p scripts/github.com/YOUR_ORG/YOUR_PROJECT
  69    ```
  70 2. Create a `deploy.sh` that builds and deploys your project:
  71
  72    ```bash
  73    #!/bin/bash
  74
  75    # Put bash in strict mode or bad things will happen.
  76    set -u
  77    set -e
  78
  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" ]]
  82    then
  83        echo "Nothing to do for ${GIT_REPO_ID}#${GIT_REF_NAME}"
  84        exit 0
  85    fi
  86
  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}"
  90
  91    pushd "${my_tmp}/${GIT_REPO_NAME}/"
  92        echo "Deploying ${GIT_REPO_ID}#${GIT_REF_NAME} ..."
  93
  94        # run an example build process
  95        npm ci
  96        npm run build
  97
  98        # deploy to an example staging site
  99        rsync -av ./ ~/srv/staging.example.com/public/
 100    popd
 101
 102    # clean up after the build
 103    rm -rf "${my_tmp}/${GIT_REPO_NAME}/"
 104    ```
 105
 106 ### How to set up a webhook
 107
 108 1. Generate a 128-bit random string:
 109    ```bash
 110    xxd -l16 -ps /dev/urandom
 111    ```
 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`
 116    - BitBucket:
 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:
 120
 121    ```bash
 122    # Github
 123    https://YOUR_DOMAIN/api/webhooks/github
 124
 125    # Gitea
 126    https://YOUR_DOMAIN/api/webhooks/gitea
 127
 128    # Bitbucket
 129    https://YOUR_DOMAIN/api/webhooks/bitbucket?access_token=YOUR_SECRET
 130    ```
 131
 132 ### How to use ENVs (and .env)
 133
 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:
 136
 137 ```bash
 138 PORT=4483
 139
 140 GITHUB_SECRET=xxxxxxxxxxx
 141 ```
 142
 143 See the
 144 [examples/dotenv](https://git.rootprojects.org/root/gitdeploy/src/branch/master/examples/dotenv)
 145 for more info.
 146
 147 ### How to use Deploy Keys & Personal Access Tokens
 148
 149 See the
 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/>.
 152
 153 ### How to reverse Proxy with HTTPS (Let's Encrypt)
 154
 155 See the [Caddy (Web Server) Cheat Sheet](https://webinstall.dev/caddy).