PullRequestService

Adds a general comment to the pull request.

Adds a line comment to a diff in a pull request.

Adds a file-level comment to the pull request.

Adds a file-level comment to the pull request.

Adds a line comment to the pull request.

Adds a reply to a comment

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

Allows a user to give their approval to a pull request. If they aren't already a participant of the pull request they are made one first. If the user has already already provided their approval this operation has no effect. A user may only approve a pull request which is in open.

Since 4.2 authors may not have their status changed.

Assigns a participant to an explicit role in pull request. Currently only reviewers may be assigned. If the user is not yet a participant in the pull request, they are made one and assigned the supplied role. If the user is already a participant in the pull request, their previous role is replaced with the supplied role unless they are already assigned the AUTHOR role which cannot be changed and will result in an UnmodifiablePullRequestRoleException being thrown.

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 a pull request comment

Get diff anchors for a given pull request and a path affected by that pull request.

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 comment for the given comment id and pull request id.

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.

Unassigns a participant from any role they may have been given in a pull request. If the user is not a participant this method has no effect. An attempt to unassign a participant from the AUTHOR role will result in an UnmodifiablePullRequestRoleException being thrown. Since 4.2 if the user is not an AUTHOR and they have no activity items associated with them in the pull request they will be completely removed. If the user has the PARTICIPANT role and they have activity items associated with them in the pull request this method has no effect. If the user has the REVIEWER role and they have activity items associated with them in the pull request this method will simply update their role to PARTICIPANT.

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

Updates the pull request comment's text

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

Allows the current user to withdraw their approval of a pull request. The user must already be a participant of the pull request else an exception is thrown. If the user has already withdrawn their approval this operation has no effect. A participant may only withdraw approval for a pull request if it open.

Since 4.2 authors may not have their status changed and non-participants may not withdraw approvals.