Package com.atlassian.bitbucket.pull

Interface PullRequestService

All Superinterfaces:
PullRequestSupplier
public interface PullRequestService extends PullRequestSupplier
A service for the management of pull requests and their comments.

About pull request IDs: Each pull request has two repositories associated with it: The repository commits will be merged from, and the repository they will be merged to. Pull request IDs are scoped to the target repository, and each method accepting a repository ID, unless otherwise documented, expects the ID of that repository. Also note that pull request IDs start from 1 in each target repository; they are not globally unique.

  • Method Details

    • addReviewer

      @Nonnull PullRequestParticipant addReviewer(int repositoryId, long pullRequestId, @Nonnull String username)
      Adds the user specified by 'username' as REVIEWER to the provided PR. If the user is already a reviewer this method has no effect.
      Parameters:
      repositoryId - the ID of the repository to which the pull request will be merged
      pullRequestId - the ID of the pull request within the repository
      username - the username for the user to be added as a reviewer
      Returns:
      the newly created or updated participant entity
      Throws:
      NoSuchPullRequestException - if no pull request with the specified ID can be found in the repository
      UnmodifiablePullRequestRoleException - if the participant is already assigned the AUTHOR role.
      InvalidPullRequestParticipantException - if the user cannot be made a reviewer because they have insufficient access to the repository
      IllegalPullRequestStateException - if the pull request is either MERGED or DECLINED
      RepositoryArchivedException - if target repository is archived
      Since:
      4.2

    • canDelete

      boolean canDelete(int repositoryId, long pullRequestId)
      Verifies if the current user can delete the specified pull request.
      Parameters:
      repositoryId - the ID of the repository to which the pull request will be merged
      pullRequestId - the ID of the pull request within the repository
      Returns:
      true if the current user has sufficient permissions to delete(PullRequestDeleteRequest) delete} the provided pull request, otherwise false. Note that the required permissions may vary depending on the role of the user in the pull request.
      Since:
      5.1

    • canMerge

      PullRequestMergeability canMerge(int repositoryId, long pullRequestId)
      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
      The goal for this method is to serve as a hint as to whether or not a given pull request can be merged by the system, rather than as an ironclad assurance that it can be.

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

      Parameters:
      repositoryId - the ID of the repository to which the pull request will be merged
      pullRequestId - the ID of the pull request within the repository
      Returns:
      the mergeability of the pull request, taking into account if it is open, has conflicts and any vetoes that RepositoryMergeChecks may have raised
      Throws:
      IllegalPullRequestStateException - if the pull request is not open

    • countCommits

      long countCommits(int repositoryId, long pullRequestId)
      Counts the number of commits a pull request has.
      Parameters:
      repositoryId - the ID of the repository to which the pull request will be merged
      pullRequestId - the ID of the pull request within the repository
      Returns:
      the number of commits in the pull request
      Throws:
      NoSuchPullRequestException - if no pull request with the specified ID can be found in the repository

    • count

      long count(@Nonnull PullRequestSearchRequest request)
      Counts the number of pull requests which match the specified search criteria.
      Parameters:
      request - the search criteria to use
      Returns:
      the number of pull requests that match the search criteria

    • countByCommit

      long countByCommit(@Nonnull PullRequestCommitSearchRequest request)
      Counts the number of pull requests containing a specified commit which match the given search criteria. Similar to count(PullRequestSearchRequest), if the request doesn't limit the search to a repository that the user has access to, the count may include pull requests the user can't see.
      Parameters:
      request - the search request to use
      Returns:
      the number of pull requests that match the search request
      Since:
      5.11

    • create

      @Nonnull PullRequest create(@Nonnull PullRequestCreateRequest request)
      Creates a pull request from the supplied details.

      Events raised:

      Parameters:
      request - the details for the new pull request
      Returns:
      the created pull request
      Throws:
      DuplicatePullRequestException - if there is already an open pull request with identical to and from repositories and branches
      EmptyPullRequestException - if the to branch is up-to-date with all of the changes on the from branch, resulting in a pull request with nothing to merge
      InvalidPullRequestTargetException - if the from or to repositories are not the same or if the from and to branches are the same
      InvalidPullRequestReviewersException - if one or more of the reviewers could not be added
      PullRequestOpenCanceledException - if opening the pull request is canceled by an event listener
      NoSuchCommitException - if the the from or to branches do not exist
      RepositoryArchivedException - if target repository is archived

    • decline

      @Nonnull PullRequest decline(@Nonnull PullRequestDeclineRequest request)
      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.
      Parameters:
      request - details for declining a pull request
      Returns:
      the updated pull request
      Throws:
      IllegalPullRequestStateException - if the pull request is not open
      NoSuchPullRequestException - if no pull request with the specified ID can be found in the repository
      PullRequestOutOfDateException - if the version of the specified pull request does not match the expected version

    • delete

      void delete(@Nonnull PullRequestDeleteRequest request)
      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.

      Parameters:
      request - details for deleting a pull request
      Throws:
      AuthorisationException - if the current user does not have permission to delete the pull request
      NoSuchPullRequestException - if no pull request with the specified ID can be found in the repository
      PullRequestDeletionDisabledException - if deletion has been disabled
      RepositoryArchivedException - if target repository is archived
      Since:
      5.1
      See Also:

    • deleteMergeConfig

      void deleteMergeConfig(@Nonnull DeletePullRequestMergeConfigRequest 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.

      Parameters:
      request - describes which merge configuration is to be deleted
      Since:
      5.2
      See Also:

    • discardReview

      void discardReview(@Nonnull PullRequestDiscardReviewRequest request)
      Discards the pull request review for the authenticated user.
      Parameters:
      request - describes the pull request discard review request
      Since:
      7.7

    • finishReview

      int finishReview(@Nonnull PullRequestFinishReviewRequest request)
      Finish a pull request review.

      The operations that will be performed when finishing a review on a pull request are:

      1. Publish any pending comments. Comments will change state from PENDING to OPEN.
      2. Add the currently authenticated user as a reviewer, and if a participant status is provided update their status.
      3. Add a general comment to the pull request if there is comment text in the request.
      Parameters:
      request - the request which contains the pull request, comment text and participant status to set on the pull request
      Returns:
      the number of pending comments that got published
      Throws:
      RepositoryArchivedException - if target repository is archived
      Since:
      7.7

    • getActivities

      @Nonnull Page<PullRequestActivity> getActivities(int repositoryId, long pullRequestId, @Nonnull PageRequest pageRequest)
      Retrieves a page of the activities for a given pull request.
      Parameters:
      repositoryId - the ID of the repository to which the pull request will be merged
      pullRequestId - the ID of the pull request within the repository
      pageRequest - the request specifying the start and limit of the page
      Returns:
      the page of activities

    • getActivitiesStartingAt

      @Nonnull PullRequestActivityPage<PullRequestActivity> getActivitiesStartingAt(int repositoryId, long pullRequestId, @Nonnull PullRequestEntityType fromType, long fromId, @Nonnull PageRequest pageRequest)
      Retrieves the page of activities that start with an entity (given its type and id) for the given pull request.

      Entity types currently accepted:

      • PullRequestEntityType.ACTIVITY to search for the page of activities starting with the supplied activity
      • PullRequestEntityType.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.
      Parameters:
      repositoryId - the ID of the repository to which the pull request will be merged
      pullRequestId - the ID of the pull request within the repository
      fromType - the type of the entity to search for
      fromId - ID of the entity to search for - either a comment ID or activity ID
      pageRequest - the request specifying the limit of the page. Note: the start property is ignored.
      Returns:
      the page of activities that contains the given activity. This page provides the ability to calculate both the next page and the previous page of results as the page may be
      Throws:
      NoSuchEntityException - if the activity can't be found.

    • getActivitiesById

      @Nonnull Set<PullRequestActivity> getActivitiesById(int repositoryId, long pullRequestId, Set<Long> activityIds)
      Retrieves the specified activities of the given pull request.
      Parameters:
      repositoryId - the ID of the repository to which the pull request will be merged
      pullRequestId - the ID of the pull request within the repository
      activityIds - the activity IDs that should be retrieved
      Returns:
      the activities that could be found. Note: There may be fewer returned activities than supplied IDs where an unknown ID is specified or where activities have since been deleted.

    • getById

      @Nullable PullRequest getById(int repositoryId, long pullRequestId)
      Retrieves a pull request by its ID, within the specified repository.
      Specified by:
      getById in interface PullRequestSupplier
      Parameters:
      repositoryId - the ID of the repository to which the pull request will be merged
      pullRequestId - the ID of the pull request within the repository
      Returns:
      the pull request found or null if there is no pull request that matches the given id

    • getCommits

      @Nonnull Page<Commit> getCommits(@Nonnull PullRequestCommitsRequest request, @Nonnull PageRequest pageRequest)
      Retrieves a page of the commits for a given pull request.
      Parameters:
      request - the repository, pull request and other properties describing the commits to return
      pageRequest - the request specifying the start and limit of the page
      Returns:
      the page of commits
      Throws:
      NoSuchPullRequestException - if no pull request with the specified ID can be found in the repository
      Since:
      6.0

    • getDiffStatsSummary

      @Nonnull DiffStatsSummary getDiffStatsSummary(@Nonnull PullRequestDiffStatsSummaryRequest request)
      Retrieves the diff stats summary of the given pull request.

      The stats summary include the total number of modified files, added lines, and deleted lines.

      Parameters:
      request - the repository, pull request path and other properties describing the diff
      Returns:
      the diff stats summary of the given pull request
      Since:
      9.1

    • getMergeBase

      @Nonnull Optional<Commit> getMergeBase(int repositoryId, long pullRequestId)
      Retrieves the best common ancestor between the latest commits of the source and target branches of the pull request.

      If more than one best common ancestor exists, only one will be returned. It is unspecified which will be returned.

      Parameters:
      repositoryId - the ID of the repository to which the pull request will be merged
      pullRequestId - the ID of the pull request within the repository
      Returns:
      the commit that represents the best common ancestor of the pull request's source and target commits, or Optional.empty() if no common ancestor could be found
      Throws:
      NoSuchPullRequestException - if no pull request with the specified ID can be found in the repository
      Since:
      8.16

    • getMergeConfig

      @Nonnull PullRequestMergeConfig getMergeConfig(@Nonnull GetPullRequestMergeConfigRequest 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. PullRequestMergeConfigType.SCM
      If merge configuration has not been applied at any level, defaults for the appropriate SCM are returned.

      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.

      Parameters:
      request - a request describing the repository, project-and-SCM or SCM to retrieve configuration for
      Returns:
      merge configuration for pull requests to the specified repository, repositories within the specified project, or repositories of the specified SCM
      Throws:
      AuthorisationException - if the requesting user does not have access to the source they're retrieving merge configuration for
      FeatureUnsupportedScmException - if the SCM does not support merge strategies
      Since:
      4.9

    • getParticipants

      @Nonnull Page<PullRequestParticipant> getParticipants(int repositoryId, long pullRequestId, @Nonnull PageRequest pageRequest)
      Retrieves a page of the participants for a given pull request.
      Parameters:
      repositoryId - the ID of the repository to which the pull request will be merged
      pullRequestId - the ID of the pull request within the repository
      pageRequest - the request specifying the start and limit of the page
      Returns:
      the page of participants

    • getReviewThreads

      @Nonnull Page<CommentThread> getReviewThreads(int repositoryId, long pullRequestId, @Nonnull PageRequest pageRequest)
      Get all the threads which have a comment and the state is pending for the currently authenticated user.
      Parameters:
      repositoryId - the ID of the repository
      pullRequestId - the ID of the pull request
      pageRequest - the page request
      Returns:
      the page of threads
      Since:
      7.7

    • merge

      @Nonnull PullRequest merge(@Nonnull PullRequestMergeRequest 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.
      Parameters:
      request - details for merging the pull request, specifying the pull request to merge, the expected version, and, optionally, a commit message and additional context
      Returns:
      the updated pull request
      Throws:
      IllegalPullRequestStateException - if the pull request is not open
      NoSuchPullRequestException - if no pull request with the specified ID can be found in the repository
      PullRequestMergeVetoedException - if the merge was canceled by an event listener or hook
      PullRequestOutOfDateException - if the version of the specified pull request does not match the expected version
      RepositoryArchivedException - if target repository is archived

    • removeReviewer

      void removeReviewer(int repositoryId, long pullRequestId, @Nonnull String username)
      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.

      Parameters:
      repositoryId - the ID of the repository to which the pull request will be merged
      pullRequestId - the ID of the pull request within the repository
      username - the reviewer's user name
      Throws:
      NoSuchPullRequestException - if no pull request with the specified ID can be found in the repository
      UnmodifiablePullRequestRoleException - if the user is the AUTHOR of the PR
      IllegalPullRequestStateException - if the pull request is either MERGED or DECLINED
      RepositoryArchivedException - if target repository is archived
      Since:
      4.2

    • reopen

      @Nonnull PullRequest reopen(int repositoryId, long pullRequestId, int version)
      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.
      Parameters:
      repositoryId - the ID of the repository to which the pull request will be merged
      pullRequestId - the ID of the pull request within the repository
      version - the expected version of the pull request
      Returns:
      the updated pull request
      Throws:
      DuplicatePullRequestException - if a pull request with the same source and target refs already exists
      IllegalPullRequestStateException - if the pull request is not declined
      NoSuchPullRequestException - if no pull request with the specified ID can be found in the repository
      PullRequestOutOfDateException - if the version of the specified pull request does not match the expected version
      RepositoryArchivedException - if target repository is archived

    • search

      @Nonnull Page<PullRequest> search(@Nonnull PullRequestSearchRequest request, @Nonnull PageRequest pageRequest)
      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
      Parameters:
      request - the search criteria to use
      pageRequest - the request specifying the start and limit of the search
      Returns:
      a page of pull requests
      Throws:
      IllegalPullRequestSearchRequestException - if PARTICIPANT_STATUS order was requested but PullRequestSearchRequest.getParticipants() is empty or contains more than one participant (since 4.4)

    • searchActivities

      @Nonnull Page<PullRequestActivity> searchActivities(@Nonnull PullRequestActivitySearchRequest request, @Nonnull PageRequest pageRequest)
      Finds a single page of pull request activities depending on the request passed in.
      Parameters:
      request - the search criteria to use
      pageRequest - the request specifying the start and limit of the search
      Returns:
      a page of pull request activities

    • searchByCommit

      @Nonnull Page<PullRequest> searchByCommit(@Nonnull PullRequestCommitSearchRequest request, @Nonnull PageRequest pageRequest)
      Finds a single page of pull requests containing a specified commit which match the given search criteria.
      Parameters:
      request - the search request to use
      pageRequest - the request specifying the start and limit of the search
      Returns:
      a page of pull requests
      Since:
      5.11

    • searchUsers

      @Nonnull Page<ApplicationUser> searchUsers(@Nonnull PullRequestParticipantSearchRequest searchRequest, @Nonnull PageRequest pageRequest)
      Finds users who have participated in pull requests based on the provided search request.
      Parameters:
      searchRequest - the search criteria to use
      pageRequest - the request specifying the start and limit of the search
      Returns:
      a page of pull request participant users
      Since:
      4.2

    • setMergeConfig

      void setMergeConfig(@Nonnull SetPullRequestMergeConfigRequest 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
      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. PullRequestMergeConfigType.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.

      Parameters:
      request - a request describing the repository, project-and-SCM or SCM to set configuration for, the default strategy to use and the set of strategies that should be enabled
      Throws:
      ArgumentValidationException - if the default merge strategy is not enabled, or if any of the enabled strategies are not supported by the associated SCM
      AuthorisationException - if the updating user does not have the required administrator permission
      FeatureUnsupportedScmException - if the SCM does not support merge strategies
      Since:
      4.9

    • setReviewerStatus

      @Nonnull PullRequestParticipant setReviewerStatus(@Nonnull PullRequestParticipantStatusRequest request)
      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.

      Parameters:
      request - a request describing the repository, pull request, last reviewed commit and participant status
      Returns:
      the newly created or updated participant entity
      Throws:
      InvalidPullRequestParticipantException - if the user cannot be made a participant because they have insufficient privileges to read the repository
      IllegalPullRequestStateException - if the pull request is not open
      PullRequestOutOfDateException - if the latest commit of the specified pull request does not match the last reviewed commit in the request
      Since:
      7.17.21, 7.21.17, 8.9.6, 8.10.6, 8.11.5, 8.12.3, 8.13.2, 8.14.1, 8.15

    • streamChanges

      void streamChanges(@Nonnull PullRequestChangesRequest request, @Nonnull ChangeCallback callback)
      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.

      Parameters:
      request - the repository, pull request and other properties describing the changes to stream
      callback - the callback to receive changes
      Throws:
      NoSuchPullRequestException - if no pull request with the specified ID can be found in the repository

    • streamCommits

      void streamCommits(@Nonnull PullRequestCommitsRequest request, @Nonnull CommitCallback callback)
      Streams commits for the specified pull request.
      Parameters:
      request - the repository, pull request and other properties describing the commits to stream
      callback - the request specifying the start and limit of the page
      Throws:
      NoSuchPullRequestException - if no pull request with the specified ID can be found in the repository
      Since:
      6.0

    • streamDiff

      void streamDiff(@Nonnull PullRequestDiffRequest request, @Nonnull DiffContentCallback callback)
      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.

      Parameters:
      request - the repository, pull request, path and other properties describing the diff to stream
      callback - the callback to receive the streamed Diff
      Throws:
      NoSuchPullRequestException - if no pull request with the specified ID can be found in the repository

    • streamDiff

      void streamDiff(@Nonnull PullRequestDiffRequest request, @Nonnull TypeAwareOutputSupplier outputSupplier)
      Streams a raw diff for a given PullRequest.
      Parameters:
      request - the repository, pull request, path and other properties describing the diff to stream
      outputSupplier - a supplier which will provide an output stream
      Since:
      6.7

    • update

      @Nonnull PullRequest update(@Nonnull PullRequestUpdateRequest request)
      Updates a pull request's title, description, and participants.

      This method will fire:

      Parameters:
      request - details for updating a pull request, including a title, description and reviewers.
      Returns:
      the updated pull request
      Throws:
      NoSuchPullRequestException - if no pull request with the specified ID can be found in the repository
      PullRequestOutOfDateException - if the version of the specified pull request does not match the expected version
      InvalidPullRequestReviewersException - if one or more of the reviewers could not be added
      DuplicatePullRequestException - if there is already an open pull request with an identical to branch
      InvalidPullRequestTargetException - if the from and new to branch are the same
      EmptyPullRequestException - if the new destination branch up-to-date is up-to-date with all of the changes from the from branch, resulting in a pull request with nothing to merge
      IllegalPullRequestStateException - if trying to update a merged pull request
      RepositoryArchivedException - if target repository is archived