The London Perl and Raku Workshop takes place on 26th Oct 2024. If your company depends on Perl, please consider sponsoring and/or attending.
 / 
WebService-BitbucketServer-0.605
River stage zero No dependents
1 ++
/ WebService::BitbucketServer::RepositoryRefSync::V1

NAME

WebService::BitbucketServer::RepositoryRefSync::V1 - Bindings for a Bitbucket Server REST API

VERSION

version 0.605

SYNOPSIS

    my $stash = WebService::BitbucketServer->new(
        base_url    => 'https://stash.example.com/',
        username    => 'bob',
        password    => 'secret',
    );
    my $api = $stash->repository_ref_sync;

DESCRIPTION

This is a Bitbucket Server REST API for RepositoryRefSync::V1.

Original API documentation created by and copyright Atlassian.

ATTRIBUTES

context

Get the instance of WebService::BitbucketServer passed to "new".

METHODS

new

    $api = WebService::BitbucketServer::RepositoryRefSync::V1->new(context => $webservice_bitbucketserver_obj);

Create a new API.

Normally you would use $webservice_bitbucketserver_obj->repository_ref_sync instead.

set_enabled

Enables or disables synchronization for the specified repository. When synchronization is enabled, branches within the repository are immediately synchronized and the status is updated with the outcome. That initial synchronization is performed before the REST request returns, allowing it to return the updated status.

The authenticated user must have REPO_ADMIN permission for the specified repository. Anonymous users cannot manage synchronization, even on public repositories. Additionally, synchronization must be available for the specified repository. Synchronization is only available if:

  • The repository is a fork, since its origin is used as upstream

  • The owning user still has access to the fork's origin, if the repository is a personal fork

    POST sync/1.0/projects/{projectKey}/repos/{repositorySlug}

Responses:

  • 200 - status, type: application/json

    The updated synchronization status for the repository, after enabling synchronization. 204 NO CONTENT is returned instead after disabling synchronization.

  • 400 - errors, type: application/json

    The JSON payload for the request did not define the "enabled" property.

  • 401 - errors, type: application/json

    The currently authenticated user has insufficient permissions to manage synchronization in the specified repository.

  • 204 - data, type: application/json

    Synchronization has successfully been disabled. 200 OK, with updated status information, is returned instead after enabling synchronization.

  • 404 - errors, type: application/json

    The specified repository does not exist.

get_status

Retrieves the synchronization status for the specified repository. In addition to listing refs which cannot be synchronized, if any, the status also provides the timestamp for the most recent synchronization and indicates whether synchronization is available and enabled. If "?at" is specified in the URL, the synchronization status for the specified ref is returned, rather than the complete repository status.

The authenticated user must have REPO_READ permission for the repository, or it must be public if the request is anonymous. Additionally, after synchronization is enabled for a repository, meaning synchronization was available at that time, permission changes and other actions can cause it to become unavailable. Even when synchronization is enabled, if it is no longer available for the repository it will not be performed.

    GET sync/1.0/projects/{projectKey}/repos/{repositorySlug}

Parameters:

  • at - string, default: none

    retrieves the synchronization status for the specified ref within the repository, rather than for the entire repository

Responses:

  • 200 - status, type: application/json

    Synchronization status for the specified repository, or specific ref within that repository.

  • 401 - errors, type: application/json

    The currently authenticated user has insufficient permissions to view the repository, or the repository is not public if the request is anonymous.

  • 404 - errors, type: application/json

    The specified repository does not exist.

synchronize

Allows developers to apply a manual operation to bring a ref back in sync with upstream when it becomes out of sync due to conflicting changes. The following actions are supported:

  • MERGE: Merges in commits from the upstream ref. After applying this action, the synchronized ref will be AHEAD (as it still includes commits that do not exist upstream.

    • This action is only supported for DIVERGED refs

    • If a "commitMessage" is provided in the context, it will be used on the merge commit. Otherwise a default message is used.

  • DISCARD: Throws away local changes in favour of those made upstream. This is a destructive operation where commits in the local repository are lost.

    • No context entries are supported for this action

    • If the upstream ref has been deleted, the local ref is deleted as well

    • Otherwise, the local ref is updated to reference the same commit as upstream, even if the update is not fast-forward (similar to a forced push)

The authenticated user must have REPO_WRITE permission for the specified repository. Anonymous users cannot synchronize refs, even on public repositories. Additionally, synchronization must be enabled and available for the specified repository.

    POST sync/1.0/projects/{projectKey}/repos/{repositorySlug}/synchronize

Responses:

  • 200 - status, type: application/json

    The requested action was successfully performed, and has updated the ref's state, but the ref if is still not in sync with upstream. For example, after applying the MERGE action, the ref will still be AHEAD of upstream. If the action brings the ref in sync with upstream, 204 NO CONTENT is returned instead.

  • 400 - errors, type: application/json

    The requested synchronization action was not understood.

  • 401 - errors, type: application/json

    The currently authenticated user has insufficient permissions to update refs within the specified repository.

  • 204 - data, type: application/json

    The requested action was successfully performed and the ref is now in sync with upstream. If the action updates the ref but does not bring it in sync with upstream, 200 OK is returned instead.

  • 501 - errors, type: application/json

    The requested synchronization action was understood by the server, but the mechanism to apply it has not been implemented.

  • 404 - errors, type: application/json

    The specified repository does not exist.

  • 409 - errors, type: application/json

    Synchronization is not available or enabled for the specified repository, or the ref is already in sync with upstream.

SEE ALSO

BUGS

Please report any bugs or feature requests on the bugtracker website https://github.com/chazmcgarvey/WebService-BitbucketServer/issues

When submitting a bug or request, please include a test-file or a patch to an existing test-file that illustrates the bug or desired feature.

AUTHOR

Charles McGarvey <chazmcgarvey@brokenzipper.com>

COPYRIGHT AND LICENSE

This software is copyright (c) 2018 by Charles McGarvey.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.