doc

Author: Bernhard Grünewaldt

README.md

@@ -28,69 +28,29 @@ Ok. Still here?! Then this might be for you :bowtie:
 
  
 
-### How it works in three sentences
+### How it works in three sentences and one picture
 
   * Plugin REST Endpoint parses the actual GitHub Webhook JSON Payload and extracts its information.
   * It then triggers all Jenkins jobs matching `{repositoryOwner}---{repositoryName}.*`
   * Lastly it injects Environment Variables into the job run for you to determine what branch and revision is to clone.
 
-
------
-
- 
-
-### Webhook - The only who tells the truth!
-
 ![](https://codeclou.github.io/jenkins-github-webhook-build-trigger-plugin/img/webhook-payload---with-overlays.png?v2)
 
 -----
 
  
 
-### How to build the plugin
-
-Jave Oracle Java 8 and Apache Maven 3 installed. And then build like this:
-
-```bash
-git clone https://github.com/codeclou/jenkins-github-webhook-build-trigger-plugin.git
-cd jenkins-github-webhook-build-trigger-plugin
-mvn clean
-mvn compile
-mvn hpi:hpi
-```
-
-Now you should have a file called `./target/github-webhook-notifier-plugin.hpi` which
-you can upload manually to Jenkins under 'Manage Plugins' → 'Advanced' → 'Upload Plugin'.
-
------
-
- 
-
-### Why?
-
-I needed something that forcefully triggers my Jenkins Jobs by passing the actual Git Commit ID.
-
-The default behaviour of existing plugins is to "decide if it needs to rebuild". Which leads
-to a state where if your job just build your `master` Branch and you create a tag of off the `master` branch
-and push that tag, that the jenkins job will not be triggered, since the revisions are equal.
- 
-
-### NOTE
-
-When using matrix-based security the 'Anonymous' user needs 'Job' `build,discover,read` rights.
-
-
-
-
 ### GitHub Webhook Configuration
 
  * **Payload URL**
-   * `https://jenkins.foo/jenkins/github-webhook-build-trigger/receive`
-   * Note: The endpoint can be called without authentication.
+   * `https://jenkins/github-webhook-build-trigger/receive`
+   * Note: 
+     * The endpoint can be called without authentication.
+     * When using matrix-based security 'Anonymous' needs 'Job' → `build,discover,read` permissions.
  * **Content type**
    * `application/json`
  * **Secret**
-   * Choose a good secret, at best a random sha512 hash
+   * Choose a good secret, at best a random sha512 hash. Use that secret for all webhooks of all your repositories.
  * **Which events ...**
    * Just the `push` event
 
@@ -117,6 +77,53 @@ And that triggers this exact id for the exact branch/tag that has been sent by t
 
 
 
+
+-----
+
+ 
+
+### Appendix
+
+**Build Plugin**
+
+Jave Oracle Java 8 and Apache Maven 3 installed. And then build like this:
+
+```bash
+git clone https://github.com/codeclou/jenkins-github-webhook-build-trigger-plugin.git
+cd jenkins-github-webhook-build-trigger-plugin
+mvn clean
+mvn compile
+mvn hpi:hpi
+```
+
+Now you should have a file called `./target/github-webhook-notifier-plugin.hpi` which
+you can upload manually to Jenkins under 'Manage Plugins' → 'Advanced' → 'Upload Plugin'.
+
+
+ 
+
+ 
+
+**What's the story behind it?**
+
+I needed something that forcefully triggers my Jenkins Jobs by passing the actual git revision and branch or tag information.
+
+The default behaviour of existing plugins is to receive the GitHub Webhook Payload, but 
+only using the `after` commit id and "deciding if it needs to rebuild the job". 
+
+Example: You are on your `master` Branch and you create a tag of off the `master` branch
+and called `1.0.0`. When pushing `1.0.0` tag, the jenkins job will not trigger an actual build.
+What happens? It will do some strange `git fetch` requests and comes to the result, that the revision
+was already built with the previous push done by `master` branch. And partly he is right. 
+Until further commits happen, the `master` branch has the same revision as the `1.0.0` tag.
+But **I want tag pushes to trigger a build anyway**. And since I hate 'API-wrappers' of stuff,
+I decided to create a single purpose tool that just passes the information of the webhook payload
+through to the job. And it is the jobs logic that can now decide what to do.
+
+
+ 
+
+
 -----