Skip to content

Added some documentation on registering for comments in README.md #130

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 1 commit into
base: master
Choose a base branch
from
Open

Added some documentation on registering for comments in README.md #130

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
26 changes: 21 additions & 5 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -44,7 +44,7 @@ However you can override this in a pipeline script by calling `setCredentials(St
pullRequest.setCredentials('John.Smith', 'qwerty4321')
```

If you plan to use this plugin to add/modify/remove comments, labels, commit statuses etc. Please ensure that the required permissions are assigned to the token supplied in the credentials (`Scan Credentials` or `Manually` supplied).
If you plan to use this plugin to add/modify/remove comments, labels, commit statuses, etc., please ensure that the required permissions are assigned to the token supplied in the credentials (`Scan Credentials` or `Manually` supplied).

# Triggers

Expand All @@ -62,16 +62,18 @@ This plugin adds the following pipeline triggers

### Limitations

The Pull Request's job/build must have run at least once for the trigger to be registered. If an initial run never takes place then the trigger won't be registered and cannot pickup on any comments made.
The Pull Request's job/build must have run at least once for the trigger to be registered. If an initial run never takes place then the trigger won't be registered and can't pick up on any comments made.

This should not be an issue in practice, because a requirement of using this plugin is that your jobs are setup automatically by the GitHub Branch Source Plugin, which will trigger an initial build when it is notified of a new Pull Request.
This should not be an issue in practice, because a requirement of using this plugin is that your jobs are set up automatically by the GitHub Branch Source Plugin, which will trigger an initial build when it is notified of a new Pull Request (unless specifically configured not to trigger that initial build). Note also that if the relevant Jenkinsfile is invalid (e.g. has merge conflicts), the trigger won't be registered, and comments will do nothing.

In projects where these limitations present an issue, one may want to take a look at [GitHub PR Comment Build plugin](https://plugins.jenkins.io/github-pr-comment-build/).

### Considerations

This trigger would be of limited usefulness for people wishing to build public GitHub/Jenkins bots, using pipeline scripts. As there is no way to ensure that a Pull Request's `Jenkinsfile` contains any triggers. Not to mention you would not want to trust just any `Jenkinsfile` from a random Pull Request/non-collaborator.

This trigger is intended to be used inside enterprise organizations:
1. Where all branches and forks just contain a token `Jenkinsfile` that delegates to the real pipeline script, using [shared libraries](https://jenkins.io/doc/book/pipeline/shared-libraries/).
This trigger is intended to be used inside enterprise organizations where:
1. All branches and forks just contain a token `Jenkinsfile` that delegates to the real pipeline script, using [shared libraries](https://jenkins.io/doc/book/pipeline/shared-libraries/).
2. Trust all their Pull Request authors.

### Parameters
Expand All @@ -98,6 +100,20 @@ pipeline {
}
```

Note that it's possible to run some code before declarative pipeline starts:

```groovy
// may return different regexes for different branches, etc.
String comment_regex = isSpecialSnowflakeBranch() ? getSpecialSnowflakeRegex() : '.*test this please.*'
// for some code (e.g. when `sh` is needed) one may need to allocate a node.

pipeline {
triggers {
issueCommentTrigger(comment_regex)
}
}
```

#### Detecting whether a build was started by the trigger in a script:

Note that the following uses `currentBuild.rawBuild` and should therefore only
Expand Down