Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Merge pull request #162 from steven-foster/JENKINS-36574
[JENKINS-36574] Custom Github status context
- Loading branch information
Showing
9 changed files
with
885 additions
and
79 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,50 @@ | ||
| = Implementation Guide | ||
|
|
||
| == Extension Points | ||
|
|
||
| === AbstractGitHubNotificationStrategy | ||
| This extension points allows traits to modify the contents of a Github status notification for a build. | ||
| There are currently 3 points in a build lifecycle where notifications are sent: | ||
|
|
||
| * On entering the queue | ||
|
|
||
| * On checkout | ||
|
|
||
| * On completion | ||
|
|
||
|
|
||
| To add or modify a status notification at these points you should implement an `AbstractGithubNotificationStrategy`. | ||
| This class will use a method, `notifications`, to create and return a list of one or more notifications to be made. | ||
| The notification strategy must also implement `equals()` and `hashCode()`. | ||
|
|
||
| A `GitHubNotificationContext` object supplies build related information to this method depending on which of the above | ||
| events has triggered. In all cases, the `SCMSource` and `SCMHead` are available. On entering the queue, the `Job` of the | ||
| build is available. On checkout and completion, the `Run` of the build is available. | ||
|
|
||
| A Github status notification has 4 parts: the `context`, `url`, `message` and `state`. | ||
|
|
||
| The `notifications` method returns a `List<GitHubNotificationRequests>` which each contain the 4 parts of a Github | ||
| notification and a boolean to indicate if errors should be ignored when sending that notification. | ||
|
|
||
| The default implementation for any of these parts can be accessed in the `GitHubNotificationContext` object. This is | ||
| useful for strategies which are only replacing a single part and want to retain the defaults for the rest. | ||
|
|
||
| The strategy or strategies are applied through a `trait`, like many other branch api extension points. | ||
| Create a class extending `SCMSourceTrait` and override the `decorateContext` to apply the strategy. `GitHubSCMSourceContext` | ||
| has two methods for applying strategies: | ||
|
|
||
| * `withNotificationStrategies` takes a list of `AbstractGitHubNotificationStrategy` and overwrites any existing strategies with | ||
| this list. | ||
|
|
||
| * `withNotificationStrategy` takes a single strategy and adds it to a list. | ||
|
|
||
| The default notification will not be sent if any strategy has been added to the `GitHubSCMSourceContext`. If your trait/strategy | ||
| sends an entirely different kind of notification and you want the default notification to be sent alongside it, you should | ||
| explicitly apply a `DefaultGitHubNotificationStrategy` to the source context in your trait. | ||
|
|
||
| Duplicate (by equality) strategies are ignored when applied to the source context. | ||
|
|
||
| ==== Implementations: | ||
| https://github.com/steven-foster/github-scm-trait-notification-context[github-scm-trait-notification-context] | ||
|
|
||
|
|
56 changes: 56 additions & 0 deletions
56
...n/java/org/jenkinsci/plugins/github_branch_source/AbstractGitHubNotificationStrategy.java
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,56 @@ | ||
| /* | ||
| * The MIT License | ||
| * | ||
| * Copyright 2017 Steven Foster | ||
| * | ||
| * Permission is hereby granted, free of charge, to any person obtaining a copy | ||
| * of this software and associated documentation files (the "Software"), to deal | ||
| * in the Software without restriction, including without limitation the rights | ||
| * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell | ||
| * copies of the Software, and to permit persons to whom the Software is | ||
| * furnished to do so, subject to the following conditions: | ||
| * | ||
| * The above copyright notice and this permission notice shall be included in | ||
| * all copies or substantial portions of the Software. | ||
| * | ||
| * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR | ||
| * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, | ||
| * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE | ||
| * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER | ||
| * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, | ||
| * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN | ||
| * THE SOFTWARE. | ||
| */ | ||
|
|
||
| package org.jenkinsci.plugins.github_branch_source; | ||
|
|
||
| import hudson.ExtensionPoint; | ||
| import hudson.model.TaskListener; | ||
|
|
||
| import java.util.List; | ||
|
|
||
| /** | ||
| * Represents a strategy for constructing GitHub status notifications | ||
| * @since TODO | ||
| */ | ||
| public abstract class AbstractGitHubNotificationStrategy implements ExtensionPoint { | ||
|
|
||
| /** | ||
| * Creates the list of {@link GitHubNotificationRequest} for the given context. | ||
| * @param notificationContext {@link GitHubNotificationContext} the context details | ||
| * @param listener the listener | ||
| * @return a list of notification requests | ||
| * @since TODO | ||
| */ | ||
| public abstract List<GitHubNotificationRequest> notifications(GitHubNotificationContext notificationContext, TaskListener listener); | ||
|
|
||
| /** | ||
| * {@inheritDoc} | ||
| */ | ||
| public abstract boolean equals(Object o); | ||
|
|
||
| /** | ||
| * {@inheritDoc} | ||
| */ | ||
| public abstract int hashCode(); | ||
| } |
64 changes: 64 additions & 0 deletions
64
...in/java/org/jenkinsci/plugins/github_branch_source/DefaultGitHubNotificationStrategy.java
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,64 @@ | ||
| /* | ||
| * The MIT License | ||
| * | ||
| * Copyright 2017 Steven Foster | ||
| * | ||
| * Permission is hereby granted, free of charge, to any person obtaining a copy | ||
| * of this software and associated documentation files (the "Software"), to deal | ||
| * in the Software without restriction, including without limitation the rights | ||
| * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell | ||
| * copies of the Software, and to permit persons to whom the Software is | ||
| * furnished to do so, subject to the following conditions: | ||
| * | ||
| * The above copyright notice and this permission notice shall be included in | ||
| * all copies or substantial portions of the Software. | ||
| * | ||
| * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR | ||
| * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, | ||
| * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE | ||
| * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER | ||
| * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, | ||
| * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN | ||
| * THE SOFTWARE. | ||
| */ | ||
|
|
||
| package org.jenkinsci.plugins.github_branch_source; | ||
|
|
||
| import hudson.model.TaskListener; | ||
|
|
||
| import java.util.Collections; | ||
| import java.util.List; | ||
|
|
||
| /** | ||
| * Default implementation of {@link AbstractGitHubNotificationStrategy} | ||
| * @since TODO | ||
| */ | ||
| public final class DefaultGitHubNotificationStrategy extends AbstractGitHubNotificationStrategy { | ||
|
|
||
| /** | ||
| * {@inheritDoc} | ||
| */ | ||
| public List<GitHubNotificationRequest> notifications(GitHubNotificationContext notificationContext, TaskListener listener) { | ||
| return Collections.singletonList(GitHubNotificationRequest.build(notificationContext.getDefaultContext(listener), | ||
| notificationContext.getDefaultUrl(listener), | ||
| notificationContext.getDefaultMessage(listener), | ||
| notificationContext.getDefaultState(listener), | ||
| notificationContext.getDefaultIgnoreError(listener))); | ||
| } | ||
|
|
||
| /** | ||
| * {@inheritDoc} | ||
| */ | ||
| @Override | ||
| public boolean equals(Object o) { | ||
| return this == o || (o != null && getClass() == o.getClass()); | ||
| } | ||
|
|
||
| /** | ||
| * {@inheritDoc} | ||
| */ | ||
| @Override | ||
| public int hashCode() { | ||
| return 42; | ||
| } | ||
| } |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.