Package com.atlassian.bitbucket.pull.mergequeue

Interface MergeQueueCheck

public interface MergeQueueCheck
Enforces a specific merge pre-condition on pull requests in a merge queue.

During merge queue processing all registered MergeQueueCheck implementations are invoked to determine if the pull request is ready to merge. The check's result controls whether the pull request can merge, should wait for a future processing cycle, or should be ejected from the queue.

Merge queue checks receive a MergeQueueCheckContext which contains a pull request and prepared merge commit. They return a MergeQueueCheckResult, which must have a state of ACCEPTED, REJECTED, or PENDING.

Concepts

  • Merge queue branch: A temporary, restricted branch created by Bitbucket that contains the prepared merge commit.
  • Prepared merge commit: The result of merging the queued pull request into its target branch, at the point the pull request reaches the front of the queue. i.e. the prepared merge commit is a descendant of other merge commits from pull requests higher in the queue. This commit can be used to run CI builds and other checks.
  • Merge queue processing: The periodic evaluation of queued pull requests, consisting of preparing merge commits, running merge queue checks, and merging or ejecting pull requests.

Implementation Guidelines

  • Performance: Checks are run frequently and sequentially. A slow check will delay all subsequent checks in the queue. Implementations should complete quickly, ideally by querying pre-computed state (e.g. build statuses) rather than performing expensive operations.
  • Idempotency: Checks may be invoked multiple times for the same pull request and prepared merge commit. Implementations should return consistent results for the same input state.
  • Recalculation of prepared merge commits: The content of the prepared merge commit may change as it is recalculated in response to pull requests being ejected from the queue. Merge queue checks that care about the code on the target branch (for example builds) should check the merge hash carefully.
  • Merge Timeout: Pull requests will be ejected from the queue if they remain in PENDING state longer than the configured merge timeout.

Registration

Implementations are registered as Atlassian plugins using the <merge-queue-check> module descriptor. See MergeQueueCheckModuleDescriptor for details.

Events

Plugins can listen to the following events to react to changes: Plugins can publish the following events to trigger merge queue processing:

Example Implementation


 public class BuildStatusMergeQueueCheck implements MergeQueueCheck {

     private final BuildStatusService buildStatusService;

     public BuildStatusMergeQueueCheck(BuildStatusService buildStatusService) {
         this.buildStatusService = buildStatusService;
     }

     @Nonnull
     @Override
     public MergeQueueCheckResult run(@Nonnull MergeQueueCheckContext context) {
         BuildStatus status = buildStatusService.getStatus(context.getMergeHash());
         return switch (status) {
             case SUCCESS -> new SimpleMergeQueueCheckResult.Builder(ACCEPTED).build();
             case IN_PROGRESS -> new SimpleMergeQueueCheckResult.Builder(PENDING)
                     .reason(new I18nKey("plugin.build.pending", status.getBuildName()))
                     .detailsUrl(status.getUrl())
                     .build();
             case FAILED -> new SimpleMergeQueueCheckResult.Builder(REJECTED)
                     .reason(new I18nKey("plugin.build.failed", status.getBuildName()))
                     .detailsUrl(status.getUrl())
                     .build();
         };
     }
 }
Since:
10.2
See Also:

  • Method Details

    • run

      @Nonnull MergeQueueCheckResult run(@Nonnull MergeQueueCheckContext context)
      Run the check on the given pull request and prepared merge commit.
      Parameters:
      context - the context to run the check on
      Returns:
      the result of the check