PullRequestService

Adds the user specified by 'username' as REVIEWER to the provided PR. If the user is already a reviewer this method has no effect.

Verifies if the current user can delete the specified pull request.

Retrieves a flag indicating whether the specified pull request can be merged by the system or must be manually merged by a user.

Even if this method returns true, there are still a variety of reasons for which merging may fail, including but not limited to:

• The version supplied when merging is out of date
• Additional changes have been pushed to the pull request's target branch and the pull request has not yet been updated accordingly

Note: If the specified pull request is declined or MERGED, this method will always return false.

Counts the number of pull requests which match the specified search criteria.

Counts the number of commits a pull request has.

Counts the number of tasks in a pull request.

Creates a pull request from the supplied repository and branch to the supplied repository and branch with the given title and description.

Events raised:

• PullRequestOpenRequestedEvent
• PullRequestOpenedEvent

Declines a pull request. The pull request must be open or an exception is thrown. The expected version of the pull request must be supplied to ensure the client is not operating on stale information.

Deletes the specified pull request, removing all activities and comments.

The from and to refs are not deleted with the pull request, to prevent accidental data loss. However, other SCM-specific data such as cached merges or special refs to provide access to pull request state will be deleted along with the pull request.

Deletes the merge configuration for the specified scope.

Repositories inherit their merge configuration from the nearest configured scope. For example, deleting a repository's merge config may cause it to inherit project or global configuration rather than reverting to the SCM's defaults.

Retrieves a page of the activities for a given pull request.

Retrieves the specified activities of the given pull request.

Retrieves the page of activities that start with an entity (given its type and id) for the given pull request.

Entity types currently accepted:

• ACTIVITY to search for the page of activities starting with the supplied activity
• COMMENT to search for the page of activities starting with the activity of the supplied comment. If the comment is not a root comment, the comment's root's activity is used.

Retrieves a pull request by its ID, within the specified repository.

Retrieves a page of the commits for a given pull request.

Retrieves the merge configuration for the specified source. All of the supported merge strategies are returned, but only enabled strategies can be specified when merging pull requests. At least one strategy, the default, is guaranteed to be enabled.

For cross-repository pull requests, the configuration for the target repository controls how the pull request can be merged.

Merge configuration can be applied at 3 different levels, listed from most specific to most generic:

1. Repository
2. Project and SCM
   • The SCM must also be considered because projects can contain multiple repositories which may not always use the same SCM
3. SCM

SCMs are not required to support merge strategies. Plugins should check support for the MERGE_STRATEGIES feature prior to calling this method. If the SCM does not support merge strategies, an exception will be thrown.

Retrieves a page of the participants for a given pull request.

Merges a pull request. The pull request must be open or an exception is thrown. The expected version of the pull request must be supplied to ensure the client is not operating on stale information.

Removes a REVIEWER from a pull request.

If the user is the AUTHOR of the pull request this method will throw IllegalPullRequestStateException; the author may not be removed.

If the user has no activity items associated with them in the pull request they will be completely removed. Otherwise they will be made a PARTICIPANT instead.

Reopens a pull request. The pull request must be declined or an exception is thrown. The expected version of the pull request must be supplied to ensure the client is not operating on stale information.

Finds a single page of pull requests depending on the request passed in. If the request specifies that the results should be sorted by participant status then only one participant may be specified in the request

Finds a single page of pull request activities depending on the request passed in.

Finds a single page of @{link Task tasks} belonging to this pull request depending on the request passed in.

Finds users who have participated in pull requests based on the provided search request.

Sets the merge configuration for the specified source, setting the default strategy and the complete set of enabled strategies. Any enabled strategy may be requested when merging a pull request, and the specified default must be enabled. The enabled strategies are verified against the SCM to ensure they are all supported.

For cross-repository pull requests, the configuration for the target repository controls how the pull request can be merged.

Merge configuration can be applied at 3 different levels, listed from most specific to most generic, and can only be updated by administrators:

1. Repository
   • Requires REPO_ADMIN permission
2. Project and SCM
   • The SCM must also be considered because projects can contain multiple repositories which may not always use the same SCM
   • Requires PROJECT_ADMIN permission
3. SCM
   • Requires global ADMIN permission

SCMs are not required to support merge strategies. Plugins should check support for the MERGE_STRATEGIES feature prior to calling this method. If the SCM does not support merge strategies, an exception will be thrown.

Allows a user to update their participation status in a pull request. If they aren't already a participant of the pull request they are made one first. A non-reviewer may not set their status to UNAPPROVED. A user may only update their status if a pull request is OPEN. This operation has no effect if the user already has their status set to the provided value.

Authors may not have their status changed.

Streams changes for the specified PullRequest to the provided ChangeCallback.

Note: Internal hard limits are applied to the number of changes which will be returned. When changes are truncated for exceeding those limits, it will be signalled to the callback.

Streams commits for the specified pull request.

Streams the Diff for the specified file path within the PullRequest to the provided DiffContentCallback. Comment anchors will be offered to the callback prior to streaming the diff, allowing them to be merged into the diff output as desired.

If the Change indicated the path being diffed was moved/renamed or copied, the srcPath should also be provided. Failure to provide both paths may result in an incorrect diff in some SCMs.

Note: Internal hard limits are applied to the diff being streamed, limiting the number of lines that can be returned. When a diff is truncated for exceeding those limits, it will be signalled to the callback.

Removes the current user as a watcher of the given pull request.

Updates a pull request's title, description, and participants.

This method will fire:

• PullRequestUpdatedEvent to inform listeners that the title or description have changed
• PullRequestReviewersUpdatedEvent to inform listeners of any reviewers assigned or unassigned from this role
• PullRequestParticipantsAddedEvent to inform listeners of any users who have participated in the pull request for the first time
• PullRequestRescopedEvent to inform listeners the the destination branch has been updated and rescope has occurred

Adds the current user as a watcher of the given pull request.