doc

Author: Bernhard Grünewaldt

README.md

@@ -75,12 +75,32 @@ magically by convention over configuration.
 
 <p align="center"><img src="https://codeclou.github.io/jenkins-github-webhook-build-trigger-plugin/img/jenkins-job-config---with-overlays.png" width="80%"></p>
 
+&nsbp;
 
+**Available Environment Variables from Webhook**
+
+| Variable | Description | Example |
+|----------|-------------|---------|
+| `$GWBT_COMMIT_BEFORE` | `before` commit id as sha1 hash from Webhook Payload, specifying the commit revision the repository was in before the event happened.  | `3be1cb4b6b86533b5dab2b0083fa9fb8b401b430` or <br> `0000000000000000000` if push event was a tag |
+| `$GWBT_COMMIT_AFTER` | `after` commit id as sha1 hash from Webhook Payload, specifying the commit revision the repository is now in. Meaning the current revision. | `2c9522c9618864808eaaede8353dbeafb996c605` |
+| `$GWBT_REF` | `ref` from Webhook Payload representing the branch or tag that was pushed | `refs/heads/{branchname}` or <br> `refs/tags/{tagname}` |
+| `$GWBT_TAG` | short tag name derived from `ref` and stripped of clutter. | When `ref` is `refs/tags/1.0.0` then it is `1.0.0`. <br>When `ref` is not a tag, it is empty! |
+| `$GWBT_BRANCH` | short branch name derived from `ref` and stripped of clutter. | When `ref` is `refs/heads/master` then it is `master`. <br>When `ref` is not a branch, it is empty! |
+| `$GWBT_REPO_CLONE_URL` | GitHub repository clone url. |  `https://github.com/{repoOwner}/{repoName}.git` <br> e.g. `https://github.com/codeclou/jenkins-github-webhook-build-trigger-plugin.git` |
+| `$GWBT_REPO_HTML_URL` |  GitHub repository browser url. |   `https://github.com/{repoOwner}/{repoName}` <br> e.g. `https://github.com/codeclou/jenkins-github-webhook-build-trigger-plugin` |
+| `$GWBT_REPO_FULL_NAME` | GitHub repository full name | `{repoOwner}/{repoName}` <br> e.g. `codeclou/jenkins-github-webhook-build-trigger-plugin` |
+| `$GWBT_REPO_NAME` | GitHub repository full name |  `{repoName}` <br> e.g. `jenkins-github-webhook-build-trigger-plugin` |
+
+
+&nsbp;
+
+**Example Build Script Snippet**
 
-Available variables:
 ```bash
 #!/bin/bash
 
+set -e
+
 echo "GWBT_COMMIT_BEFORE:  $GWBT_COMMIT_BEFORE"
 echo "GWBT_COMMIT_AFTER:   $GWBT_COMMIT_AFTER"
 echo "GWBT_REF:            $GWBT_REF"
@@ -90,7 +110,74 @@ echo "GWBT_REPO_CLONE_URL: $GWBT_REPO_CLONE_URL"
 echo "GWBT_REPO_HTML_URL:  $GWBT_REPO_HTML_URL"
 echo "GWBT_REPO_FULL_NAME: $GWBT_REPO_FULL_NAME"
 echo "GWBT_REPO_NAME:      $GWBT_REPO_NAME"
+
+#
+# Cleanup before run
+#
+rm -rf $WORKSPACE/\.git || true
+rm -rf $WORKSPACE/* || true
+cd $WORKSPACE
+
+#
+# Prevent manual Job starts
+#
+if [[ -z "$GWBT_COMMIT_AFTER" ]]
+then
+    echo "I DON'T WANT JOBS STARTED MANUALLY! ONLY VIA GITHUB WEBHOOK!"
+    exit 1
+fi
+
+
+#
+# Only Build Branches
+#
+if [ -z "$GWBT_BRANCH" ]
+then
+	echo "THIS PUSH IS NOT INSIDE A BRANCH. I DON'T LIKE IT!"
+    exit 1
+fi
+
+#
+# Clone specific branch
+#
+git clone --single-branch \
+          --branch $GWBT_BRANCH \
+          https://github.com/${GWBT_REPO_FULL_NAME}.git \
+          source
+
+#
+# Switch to specific revision
+#
+cd source
+git reset --hard $GWBT_COMMIT_AFTER
+
+#
+# Trigger build script inside cloned repository
+#
+bash jenkins.sh
+```
+
+
+&nsbp;
+
+**Example Build Script Snippet for Cloning Private Repositories**
+
+It is best to use [Personal Access Tokens](https://help.github.com/articles/creating-a-personal-access-token-for-the-command-line/). 
+Put a Global Environment Variable named `GITHUB_AUTH_TOKEN` in your Jenkins Configuration or specify at Job level.
+
+Then you can clone a private repository like this:
+
+```bash
+#
+# Clone specific branch
+#
+git clone --single-branch \
+          --branch $GWBT_BRANCH \
+          https://${GITHUB_AUTH_TOKEN}@github.com/${GWBT_REPO_FULL_NAME}.git \
+          source
 ```
+
+
 -----
 
 &nbsp;