Move GitHub/Gitlab webhook docs from GitHub wiki

Inedo · Nov 18, 2019 · ee6353c · ee6353c
1 parent 65d0249
commit ee6353c
Show file tree

Hide file tree

Showing 5 changed files with 234 additions and 5 deletions.
diff --git a/BuildMaster/builds/continuous-integration/build-triggers-and-monitors.md b/BuildMaster/builds/continuous-integration/build-triggers-and-monitors.md
@@ -21,7 +21,7 @@ The default behavior of each of these triggers is to create a new build in eithe
 ##  Executing Custom OtterScript on Trigger {#custom-plan data-title="Executing Custom Plan"}
 You can also configure a build trigger to *execute a custom plan*, which allows you to enter the name of an application-level or system-level OtterScript plan.
 
-During execution, any additional context from the commit will be  [available via deployment variables](/docs/buildmaster/builds/continuous-integration/build-triggers-and-monitors/repository-monitors#ci-plans)  to support more complex use-cases:
+During execution, any additional context from the commit will be  [available via deployment variables](/docs/buildmaster/builds/continuous-integration/build-triggers-and-monitors/repository-monitors#variables)  to support more complex use-cases:
 
 {.docs}
 -   Automatically creating a release & build when a new branch is created by combining the  `Ensure-Release`  and  `Create-Build`  operations

diff --git a/...aster/builds/continuous-integration/build-triggers-and-monitors/github-hooks.md b/...aster/builds/continuous-integration/build-triggers-and-monitors/github-hooks.md
@@ -0,0 +1,120 @@
+---
+title: GitHub Webhooks
+subtitle: Configuring GitHub Webhook Monitors
+show-headings-in-nav: true
+sequence: 300
+keywords: buildmaster, builds, github, webhook-monitors
+---
+
+BuildMaster can accept GitHub webhook events in order to:
+
+{.docs}
+ - Create a build in a specific application
+ - Execute a plan for more customizable use-cases
+
+## Pre-requisites
+
+The following pre-requisites are required to integrate GitHub webhooks with BuildMaster:
+
+{.docs}
+ - GitHub account with at least 1 repository or organization
+ - BuildMaster v6.1 or later installed
+ - Inbound firewall rule added for BuildMaster's website port on the BuildMaster server
+
+## Configuring GitHub
+
+GitHub supports webhooks at the repository or organization level. In most cases, the organization level is preferable because only a single webhook endpoint needs to be configured.
+
+To create a webhook, visit the *Settings* > *Webhooks* section of the repository or organization. Set the following options:
+
+{.docs}
+ - **Payload URL**: *will be generated in next step*
+ - **Content type**: application/json
+ - **Secret**: *create a secure token and note it for next step*
+ - **SSL verification**: *for security this should be enabled, requires a valid certificate configuration on the webserver*
+ - **Events**: Just the push event
+ - **Active**: checked
+
+## Configuring BuildMaster
+
+In BuildMaster, visit the *Administration* > *Build Triggers & Scheduled Jobs* page and click *Create New Build Trigger* to add the webhook monitor. Creating a GitHub Webhook Monitor includes the following options:
+
+{.docs}
+ - **Run for application**: if a specific application is selected, builds will be created for any active releases in that application. If no application is selected, the specified global plan is executed instead (see below for an [example](#example-plan))
+ - **Secret token**: *this must match the Secret field entered on the GitHub side*
+ - **Action**: whether to create a new build, execute a plan, or disable the webhook monitor
+ - **Create variables**: specifies whether `$Branch` or `$CommitHash` will automatically be created as build variables
+ - **Plan**: a plan that will be executed if "execute a plan" is the selected action, scoped to an application if specified, otherwise a global plan
+ - **Name**: a friendly name describing the webhook endpoint that also functions as the identifier in the generated payload URL. Only alphanumeric characters, dashes, and underscores are permitted
+
+Once saved, the payload URL, relative to the BuildMaster host, will be visible on the overview page, e.g. `/api/hooks/GitHubHook`.
+
+## Completing GitHub Configuration
+
+Once the webhook monitor is created in BuildMaster, enter that URL relative to the publicly-accessible BuildMaster host as the payload URL, for example:
+
+`https://buildmaster.inedo.com/api/hooks/GitHubHook`
+
+Once the webhook is saved, BuildMaster is ready to accept GitHub push events. 
+
+To test the configuration, simply push a commit or edit a page directly on GitHub, then use the *Settings* > *Webhooks* > *Edit* page to view the data that was sent to BuildMaster, along with the response.
+
+## Custom Plans
+
+If a plan is specified in the BuildMaster webhook configuration, it will execute instead of creating builds for the webhook's associated application. This plan has access to some [default variables](/docs/buildmaster/builds/continuous-integration/build-triggers-and-monitors/repository-monitors#variables), but GitHub also supports:
+
+{.docs}
+ - `%GitHub.Ref` - the full ref referenced by the commit
+ - `%GitHub.HeadCommit.Message` - the message associated with the commit
+ - `%GitHub.Repository.FullName` - the full name of the repository including the organization
+ - `%GitHub.Compare` - the URL that shows the diff against the previous commit
+
+Custom plans are ideal for several use-cases:
+
+ - Creating builds in multiple applications with a single webhook event
+ - Ensuring a release exists for a feature branch (e.g. `Ensure-Release(...)`, `Create-Build(...)`)
+ - Storing commit IDs, branch names, or commit messages as build configuration variables
+
+### Example Plan
+
+The following is an example plan created at the system level that supports creating builds for an entire organization, specifically the one used to trigger builds for all active releases of extensions in the [Inedo organization](https://github.com/inedo) on GitHub:
+
+```
+##AH:UseTextMode
+
+Log-Debug "Webhook received for $Repository repository (Branch=$Branch)";
+
+if $Branch == master && $MatchesRegex($Repository, ^inedox-.`$*)
+{
+    set $appName = $Substring($Repository, 7);
+    Log-Debug "Looking for $appName application...";
+    
+    if $ApplicationExists($appName)
+    {
+        Log-Debug "$appName application found. Creating build...";
+        
+        Create-Build
+        (
+            Application: $appName
+        );
+    }
+}
+```
+
+## Troubleshooting
+
+Common issues that arise are:
+
+##### The BuildMaster server is inaccessible from the internet:
+
+In this case, [Repository Monitors](/docs/buildmaster/builds/continuous-integration/build-triggers-and-monitors/repository-monitors) may be more suitable because requests are initiated from BuildMaster.
+
+##### No builds are created:
+
+When no custom plan is specified, builds are only triggered for the latest *active* releass in an application. If a custom plan is specified, then that plan is responsible for enumerating applications and/or releases, and also creating builds.
+
+##### Logs:
+
+The BuildMaster logs for a specific trigger (assuming the request ever reaches BuildMaster) are found on the *Administration* > *Executions* page. Filter by *Mode: Build Trigger* to view them.
+
+The GitHub Webhooks page shows all webhook requests, request body, and responses, with an option to resend the request.
diff --git a/...aster/builds/continuous-integration/build-triggers-and-monitors/gitlab-hooks.md b/...aster/builds/continuous-integration/build-triggers-and-monitors/gitlab-hooks.md
@@ -0,0 +1,109 @@
+---
+title: GitLab Webhooks
+subtitle: Configuring GitLab Webhook Monitors
+show-headings-in-nav: true
+sequence: 300
+keywords: buildmaster, builds, gitlab, webhook-monitors
+---
+
+BuildMaster can accept GitLab webhook events in order to:
+
+{.docs}
+ - Create a build in a specific application
+ - Execute a plan for more customizable use-cases
+ - 
+## Pre-requisites
+
+The following pre-requisites are required to integrate GitLab webhooks with BuildMaster:
+
+{.docs}
+ - GitLab account with at least 1 project or group
+ - BuildMaster v6.1 or later installed
+ - Inbound firewall rule added for BuildMaster's website port on the BuildMaster server
+
+## Configuring GitLab
+
+GitLab supports webhooks at the project or group level. In most cases, the group level is preferable because only a single webhook endpoint needs to be configured. However, the paid edition of GitLab is required to configure a group-level webhook.
+
+To create a webhook, visit the *Settings* > *Integrations* page under the project or group. Set the following options:
+
+{.docs}
+ - **URL**: *will be generated in next step*
+ - **Secret Token**: *create a secure token and note it for next step*
+ - **Trigger**: Push events, configure desired branches
+ - **SSL verification**: *for security this should be enabled, requires a valid certificate configuration on the webserver*
+
+## Configuring BuildMaster
+
+In BuildMaster, visit the *Administration* > *Build Triggers & Scheduled Jobs* page and click *Create New Build Trigger* to add the webhook monitor. Creating a GitLab Webhook Monitor includes the following options:
+
+{.docs}
+- **Run for application**: if a specific application is selected, builds will be created for any active releases in that application. If no application is selected, the specified global plan is executed instead (see below for an [example](#example-plan))
+ - **Secret token**: *this must match the Secret field entered on the GitLab side*
+ - **Action**: whether to create a new build, execute a plan, or disable the webhook monitor
+ - **Create variables**: specifies whether `$Branch` or `$CommitHash` will automatically be created as build variables
+ - **Plan**: a plan that will be executed if "execute a plan" is the selected action, scoped to an application if specified, otherwise a global plan
+ - **Name**: a friendly name describing the webhook endpoint that also functions as the identifier in the generated payload URL. Only alphanumeric characters, dashes, and underscores are permitted
+
+Once saved, the payload URL, relative to the BuildMaster host, will be visible on the overview page, e.g. `/api/hooks/GitLabHook`.
+
+## Completing GitLab Configuration
+
+Once the webhook receiver is created in BuildMaster, enter that URL relative to the publicly-accessible BuildMaster host as the URL, for example:
+
+`https://buildmaster.inedo.com/api/hooks/GitLabHook`
+
+Once the webhook is saved, BuildMaster is ready to accept GitLab push events. 
+
+To test the configuration, simply push a commit or edit a page directly on GitLab, then use the *Integrations* > *Edit Webhook* page to view the data that was sent to BuildMaster, along with the response.
+
+## Custom Plans
+
+If a plan is specified in the BuildMaster webhook configuration, it will execute instead of creating builds for the webhook's associated application. This plan has access to some [default variables](/docs/buildmaster/builds/continuous-integration/build-triggers-and-monitors/repository-monitors#variables), but GitLab also supports:
+
+{.docs}
+ - `%GitLab.Ref` - the full ref referenced by the commit
+ - `%GitLab.HeadCommit.Message` - the message associated with the latest commit
+ - `%GitLab.UserName` - the name of the author of the latest commit
+ - `%GitLab.Project.Namespace` - the group name of the repository
+
+Custom plans are ideal for several use-cases:
+
+{.docs}
+ - Creating builds in multiple applications with a single webhook event
+ - Ensuring a release exists for a feature branch (e.g. `Ensure-Release(...)`, `Create-Build(...)`)
+ - Storing commit IDs, branch names, or commit messages as build configuration variables
+
+### Example Plan
+
+The following is a simple example plan created at the system level that supports creating builds for certain projects in GitLab, allowing the same webhook URL to be used across them:
+
+```
+##AH:UseTextMode
+
+Create-Build
+(
+    Application: $Repository,
+    Variables: %(ReleaseCandidate: false)
+);
+```
+
+A more advanced example can be found in the [GitHub instructions](github-hooks).
+
+## Troubleshooting
+
+Common issues that arise are:
+
+##### The BuildMaster server is inaccessible from the internet:
+
+In this case, [Repository Monitors](/docs/buildmaster/builds/continuous-integration/build-triggers-and-monitors/repository-monitors) may be more suitable because requests are initiated from BuildMaster.
+
+##### No builds are created:
+
+When no custom plan is specified, builds are only triggered for the latest *active* releass in an application. If a custom plan is specified, then that plan is responsible for enumerating applications and/or releases, and also creating builds.
+
+##### Logs:
+
+The BuildMaster logs for a specific trigger (assuming the request ever reaches BuildMaster) are found on the *Administration* > *Executions* page. Filter by *Mode: Build Trigger* to view them.
+
+The GitLab Integrations page shows all webhook requests, request body, and responses, with an option to resend the request.
diff --git a/...uilds/continuous-integration/build-triggers-and-monitors/repository-monitors.md b/...uilds/continuous-integration/build-triggers-and-monitors/repository-monitors.md
@@ -1,7 +1,7 @@
 ---
 title: Repository Monitors
 show-headings-in-nav: true
-sequence: 900
+sequence: 100
 keywords: buildmaster, releases, builds, monitors
 ---
 

diff --git a/...r/builds/continuous-integration/build-triggers-and-monitors/webhook-monitors.md b/...r/builds/continuous-integration/build-triggers-and-monitors/webhook-monitors.md
@@ -1,7 +1,7 @@
 ---
 title: Webhook Monitors
 show-headings-in-nav: true
-sequence: 900
+sequence: 200
 keywords: buildmaster, releases, builds, webhook-monitors
 ---
 
@@ -22,9 +22,9 @@ Once these options are configured, a URL (relative to the BuildMaster host) will
 
 ## GitHub Webhook Monitor {#github data-title="GitHub Hooks"}
 
-In order for BuildMaster to receive webhooks from GitHub, a GitHub Webhook Monitor must be created in BuildMaster first, followed by adding a webhook in GitHub itself. See the [Configuring GitHub Hooks](https://github.com/Inedo/inedox-git/wiki/configuring-github-hooks) documentation for step-by-step instructions.
+In order for BuildMaster to receive webhooks from GitHub, a GitHub Webhook Monitor must be created in BuildMaster first, followed by adding a webhook in GitHub itself. See the [GitHub Webhooks](github-hooks) documentation for step-by-step instructions.
 
 ## GitLab Webhook Monitor {#gitlab data-title="GitLab Hooks"}
 
-In order for BuildMaster to receive webhooks from GitLab, a GitLab Webhook Monitor must be created in BuildMaster first, followed by adding a webhook in GitLab itself. See the [Configuring GitLab Hooks](https://github.com/Inedo/inedox-git/wiki/configuring-gitlab-hooks) documentation for step-by-step instructions.
+In order for BuildMaster to receive webhooks from GitLab, a GitLab Webhook Monitor must be created in BuildMaster first, followed by adding a webhook in GitLab itself. See the [GitLab Webhooks](gitlab-hooks) documentation for step-by-step instructions.