Package com.atlassian.bitbucket.repository.sync

Interface RefSyncService

public interface RefSyncService
Describes a service for synchronizing refs between repositories and their upstream. For example, for a fork, the upstream might be its origin. The goal is to allow developers working on downstream repositories, like forks, to keep up to date with upstream without manually fetching from upstream and then pushing downstream.

  • Method Summary

    Modifier and Type
    Method
    Description
    RefSyncStatus
    getStatus(com.atlassian.bitbucket.repository.Repository repository)
    Retrieves the complete status for synchronization of the specified repository, returning null if synchronization has not been configured.
    RejectedRef
    getStatus(com.atlassian.bitbucket.repository.Repository repository, String refId)
    Retrieves the status a single ref within the specified repository.
    boolean
    isAvailable(com.atlassian.bitbucket.repository.Repository repository)
    Retrieves a flag indicating whether ref synchronization can be enabled for the specified repository.
    boolean
    isEnabled(com.atlassian.bitbucket.repository.Repository repository)
    Retrieves a flag indicating whether ref synchronization has been enabled for the specified repository.
    void
    setEnabled(com.atlassian.bitbucket.repository.Repository repository, boolean enabled)
    Enables or disables ref synchronization for the specified repository.
    void
    synchronize(RefSyncRequest request)
    Performs a specific action to synchronize a ref within a specified repository.

  • Method Details

    • getStatus

      @Nullable RefSyncStatus getStatus(@Nonnull com.atlassian.bitbucket.repository.Repository repository)
      Retrieves the complete status for synchronization of the specified repository, returning null if synchronization has not been configured.
      Parameters:
      repository - the repository to retrieve synchronization status for
      Returns:
      the complete status, detailing all out-of-sync refs, or null if synchronization has not been configured for the specified repository

    • getStatus

      @Nullable RejectedRef getStatus(@Nonnull com.atlassian.bitbucket.repository.Repository repository, @Nonnull String refId)
      Retrieves the status a single ref within the specified repository. If the ref is in sync with the repository's origin, null will be returned.
      Parameters:
      repository - the repository to check the ref in
      refId - the ref to check within the specified repository
      Returns:
      status details for the specified ref within the repository, if it is not in sync, or null if synchronization has not been configured for the specified repository or the ref is in sync

    • isAvailable

      boolean isAvailable(@Nonnull com.atlassian.bitbucket.repository.Repository repository)
      Retrieves a flag indicating whether ref synchronization can be enabled for the specified repository.

      Synchronization is not available for:

      • Repositories with no origin, as there is no upstream repository to synchronize with
      • Personal forks for which the owning user has lost read access to the origin, as synchronizing refs would expose commits the owner does not have access to

      Whether synchronization is available can change over time. For example, for personal forks, the owner's permissions for the origin repository can be revoked. Even if synchronization is already enabled, if it is no longer available it will not be performed.

      Parameters:
      repository - the repository to check
      Returns:
      true if synchronization is available for the specified repository; otherwise, false

    • isEnabled

      boolean isEnabled(@Nonnull com.atlassian.bitbucket.repository.Repository repository)
      Retrieves a flag indicating whether ref synchronization has been enabled for the specified repository.

      Note: Even if synchronization is enabled, if it is no longer available it will not be performed.

      Parameters:
      repository - the repository to check
      Returns:
      true if synchronization has been enabled for the specified repository; otherwise, false

    • setEnabled

      void setEnabled(@Nonnull com.atlassian.bitbucket.repository.Repository repository, boolean enabled)
      Enables or disables ref synchronization for the specified repository.

      When synchronization is disabled, any information about which refs are or are not in sync is lost. When synchronization is first enabled, no immediate synchronization is performed. The next push to the upstream repository will trigger synchronization and will add or update refs as appropriate.

      Note: If synchronization is disabled and refs are removed from the upstream repository, when synchronization is re-enabled those refs will never be removed unless a new ref appears in the upstream repository and is later deleted. To ensure the most consistent state for refs, synchronization should be left enabled.

      Parameters:
      repository - the repository to enable or disable synchronization for
      enabled - true to enable synchronization; otherwise, false to disable it
      Throws:
      RefSyncNotAvailableException - if synchronization is not available for the specified repository

    • synchronize

      void synchronize(@Nonnull RefSyncRequest request)
      Performs a specific action to synchronize a ref within a specified repository. Some actions may support additional parameters to control their behaviour. Such parameters are specified in the context on the request.
      Parameters:
      request - a context describing a repository and ref to synchronize, and the action to perform
      Throws:
      com.atlassian.bitbucket.AuthorisationException - if called anonymously, or if the calling user does not have write access to the repository they are trying to synchronize in
      RefAlreadySynchronizedException - if the specified ref is already in sync with its upstream, or if a merge was requested for a ref which has not diverged from its upstream
      RefSyncNotAvailableException - if synchronization is not available for the specified repository, even if it is enabled (meaning at some point previous it was available)
      RefSyncNotEnabledException - if synchronization is not enabled for the specified repository