Issue #125 new

Document REST API for configuring Workzone

J.T. Conklin
created an issue

We have nearly 100 repos in a project that is rolling out Workzone. Stash admins like myself are being asked to make policy changes fairly often as management becomes more familiar with what we can do with Stash and Workzone. Making these changes via the web UI is painful.

Official response

  • Ulrich Kuhnhardt [Izymes] repo owner

    As for REST API documentation - we’ve been trying to follow advice in https://developer.atlassian.com/docs/atlassian-platform-common-components/rest-api-development/documenting-your-apis-with-the-atlassian-rest-api-browser but to no avail - the REST API browser does not seem to pick up our java doc efforts. We’re currently checking with Atlassian.

    To discover and use the workzone rest api follow this pattern:

    Reviewers

    GET

    Get http://localhost:7990/rest/workzoneresource/latest/branch/reviewers/PROJ/repo and check the JSON data.

    [
      {
        "projectKey": "PROJ",
        "repoSlug": "repo",
        "refName": "refs/heads/develop",
        "users": [
          {
            "name": "agrant",
    ….
      },
      {
        "projectKey": "PROJ",
        "repoSlug": "repo",
        "refName": "refs/heads/master",
        "users": [
    
        ],
        "groups": [
    
        ],
        "mandatoryUsers": [
          {
            "name": "emurphy",
    ….
    

    It’s an array where the refName (branch name), projectKey and repoSlug forms the ‘key’ under which the config is stored.

    POST

    To store a config for a project/repo/branch POST a single array entry per branch.

    POST http://localhost:7990/rest/workzoneresource/latest/branch/reviewers/PROJ/repo with the following JSON data payload (example)

    {"projectKey”:"OTHER_PROJECT","repoSlug”:"OTHER_REPO","refName":"refs/heads/develop","users":[{"name":"agrant"}],"groups":["team-leads"],"mandatoryUsers":[],"mandatoryGroups":["mandatory-reviewers"],"topSuggestedReviewers":"1","daysInPast":0}
    

    This way you can copy existing proj/repo/ref reviewer configurations to other proj/repos

    DELETE

    To delete a project/repo/branch reviewer configuration send a DELETE request of a single reviewers array entry.

    DELETE http://localhost:7990/rest/workzoneresource/latest/branch/reviewers/PROJ/repo with the following JSON data payload (example)

    {"projectKey”:"OTHER_PROJECT","repoSlug”:"OTHER_REPO","refName":"refs/heads/develop","users":[{"name":"agrant"}],"groups":["team-leads"],"mandatoryUsers":[],"mandatoryGroups":["mandatory-reviewers"],"topSuggestedReviewers":"1","daysInPast":0}
    

    Auto-Mergers

    Same pattern as above, GET http://localhost:7990/rest/workzoneresource/latest/branch/automerge/PROJ/repo to get all branch auto-merge definitions for a proj/repo. Then POST a single entry per branch back to server to modify or create a new proj/repo configuration.

    Let me know if that would be an acceptable workaround until we sort out the REST API browser doco issues.

    Workflow (Hooks)

    The REST endpoint is http://localhost:7990/rest/workzoneresource/latest/workflow/PROJ/repo - but for POST request only.

    To enable/disable hooks the payload is

    {"projectKey":"PROJ","repoSlug":"repo","pushAfterPullReq":false,"unapprovePullReq":false}
    

    The payload "projectKey" value must be equal to the /PROJ/ path parameter. The payload "repoSlug" value must be equal to the /repo path parameter.

    Note that workzone does not follow the common Stash REST endpoint pattern of /project/{PROJ_KEY}/repo/{REPO_SLUG}. Workzone assumes /{PROJ_KEY}/{REPO_SLUG}

Comments (12)

  1. Ulrich Kuhnhardt [Izymes] repo owner

    As for REST API documentation - we’ve been trying to follow advice in https://developer.atlassian.com/docs/atlassian-platform-common-components/rest-api-development/documenting-your-apis-with-the-atlassian-rest-api-browser but to no avail - the REST API browser does not seem to pick up our java doc efforts. We’re currently checking with Atlassian.

    To discover and use the workzone rest api follow this pattern:

    Reviewers

    GET

    Get http://localhost:7990/rest/workzoneresource/latest/branch/reviewers/PROJ/repo and check the JSON data.

    [
      {
        "projectKey": "PROJ",
        "repoSlug": "repo",
        "refName": "refs/heads/develop",
        "users": [
          {
            "name": "agrant",
    ….
      },
      {
        "projectKey": "PROJ",
        "repoSlug": "repo",
        "refName": "refs/heads/master",
        "users": [
    
        ],
        "groups": [
    
        ],
        "mandatoryUsers": [
          {
            "name": "emurphy",
    ….
    

    It’s an array where the refName (branch name), projectKey and repoSlug forms the ‘key’ under which the config is stored.

    POST

    To store a config for a project/repo/branch POST a single array entry per branch.

    POST http://localhost:7990/rest/workzoneresource/latest/branch/reviewers/PROJ/repo with the following JSON data payload (example)

    {"projectKey”:"OTHER_PROJECT","repoSlug”:"OTHER_REPO","refName":"refs/heads/develop","users":[{"name":"agrant"}],"groups":["team-leads"],"mandatoryUsers":[],"mandatoryGroups":["mandatory-reviewers"],"topSuggestedReviewers":"1","daysInPast":0}
    

    This way you can copy existing proj/repo/ref reviewer configurations to other proj/repos

    DELETE

    To delete a project/repo/branch reviewer configuration send a DELETE request of a single reviewers array entry.

    DELETE http://localhost:7990/rest/workzoneresource/latest/branch/reviewers/PROJ/repo with the following JSON data payload (example)

    {"projectKey”:"OTHER_PROJECT","repoSlug”:"OTHER_REPO","refName":"refs/heads/develop","users":[{"name":"agrant"}],"groups":["team-leads"],"mandatoryUsers":[],"mandatoryGroups":["mandatory-reviewers"],"topSuggestedReviewers":"1","daysInPast":0}
    

    Auto-Mergers

    Same pattern as above, GET http://localhost:7990/rest/workzoneresource/latest/branch/automerge/PROJ/repo to get all branch auto-merge definitions for a proj/repo. Then POST a single entry per branch back to server to modify or create a new proj/repo configuration.

    Let me know if that would be an acceptable workaround until we sort out the REST API browser doco issues.

    Workflow (Hooks)

    The REST endpoint is http://localhost:7990/rest/workzoneresource/latest/workflow/PROJ/repo - but for POST request only.

    To enable/disable hooks the payload is

    {"projectKey":"PROJ","repoSlug":"repo","pushAfterPullReq":false,"unapprovePullReq":false}
    

    The payload "projectKey" value must be equal to the /PROJ/ path parameter. The payload "repoSlug" value must be equal to the /repo path parameter.

    Note that workzone does not follow the common Stash REST endpoint pattern of /project/{PROJ_KEY}/repo/{REPO_SLUG}. Workzone assumes /{PROJ_KEY}/{REPO_SLUG}

  2. Francisca Munhoz

    I'm using ruby and I have tried to add reviewers to the workzone via API, would you be able to confirm what is the right way to call the api?

    example: 'https://stash.url/rest/api/1.0/projects/#{project}/repos/#{repo}/workzoneresource/reviewers'`

    reviewers_settings = {
        :projectKey            => project,
        :repoSlug              => repo,
        :refName               => 'refs/heads/dev',
        :users                 => '',
        :groups                => 'puppet_reviewers',
        :mandatoryUsers        => '',
        :mandatoryGroups       => '',
        :topSuggestedReviewers => '1',
        :daysInPast            => '90'
      }.to_json
      rs = "-d '" + reviewers_settings + "'"
      reviewers_request = `curl -u #{username}:#{password}  -H "Content-Type: application/json" -X POST #{rs} 'https://stash.url/rest/api/1.0/projects/#{project}/repos/#{repo}/workzoneresource/reviewers'`
      response = JSON.parse(reviewers_request)
    
  3. Francisca Munhoz

    Thanks a lot, it worked perfectly! Another question, to setup the automerge, what the params that I need to pass? I'll need to setup Destination Branch, Merger, Reviewers approval quota and Delete Source Branch. Where can I find the documentation about the params?

    Thanks again!

  4. Ulrich Kuhnhardt [Izymes] repo owner

    Hi Francisca,

    there is no official REST documentation yet. Atlassian's suggested way to use a REST API browser in combination with annotations does not seem to work for Bitbucket Server.

    Here is what you can do to configure Workzone automerge with curl

    Create a sample configuration for a repository via the UI - log the network traffic from the browser when you save the auto-merge configuration. Copy the JSON payload and modify for other repositories.

    http://localhost:7993/rest/workzoneresource/latest/branch/automerge/PROJ/repo

    {
      "refName": "refs/heads/master",
      "srcRefName": "",
      "automergeUsers": [
        {
          "name": "user",
          "emailAddress": "user@local",
          "active": true,
          "slug": "user",
          "type": "NORMAL"
        }
      ],
      "approvalQuotaEnabled": true,
      "approvalQuota": "60",
      "groupQuota": "0",
      "watchBuildResult": false,
      "requiredBuildsCount": "",
      "requiredSignaturesCount": "",
      "deleteSourceBranch": true
    }
    
  5. Francisca Munhoz

    Thanks a lot! It works now!

    I have to say the stash api docs is a bit confused. :)

    Do you know what is the url to call to enable pull requests? Example: https://stash.com/projects/aaaaa/repos/bbbbbb/settings/pull-requests and the url to set Branching model? Example: https://stash.com/plugins/servlet/branchmodel/projects/aaaaa/repos/bbbbbb I know it is not related to the workzone, but if you have done that before I would really appreciate you help :)

    For the add_branchmodel() url there is no POST method on the documentation only GET and for enable_pull_requests() it is returning 404.

    def add_branchmodel(project = "", repo = "", username = "", password = "") 
      project = 'aaaaa'
      repo = 'bbbbbb'
      username = 'cccc'
      password = `read -s -p "Stash Password: " password; echo $password`.chomp
    
      branch_settings = {
        :projectKey    => project,
        :repoSlug      => repo,
        :development   => ['id' => 'refs/heads/dev', 'displayId' => 'dev', 'isDefault' => true],
        :production    => [],
        :merger        => [{
          :name        => 'test'
        }],
        :autoMerge     => 'on', 
      }.to_json
      puts branch_settings
      data = "-d '" + branch_settings + "'"
      branchmodel_request = `curl -u #{username}:#{password}  -H "Content-Type: application/json" -X POST #{data} 'https://stash.com/rest/branch-utils/1.0/projects/#{project}/repos/#{repo}/branchmodel'`
      puts branchmodel_request
    end
    
    def enable_pull_requests(project = "", repo = "", username = "", password = "") 
      project = 'aaaaa'
      repo = 'bbbbbb'
      username = 'cccc'
      password = `read -s -p "Stash Password: " password; echo $password`.chomp
    
      pull_settings = {
        :requiredApprovers      => 'on',
        :requiredApproversCount => '1',
        :requiredBuilds         => '',
        :requiredCount          => '',
      }.to_json
      pr = "-d '" + pull_settings + "'"
      pull_request = `curl -u #{username}:#{password}  -H "Content-Type: application/json" -X POST #{pr} 'https://stash.com/rest/api/1.0/projects/#{project}/repos/#{repo}/settings/pull-requests'`
      puts pull_request
    end
    
    add_branchmodel()
    enable_pull_requests()
    

    Thanks in advance!

  6. Ulrich Kuhnhardt [Izymes] repo owner

    Hi Franzisca,

    I understand that you need to configure other repository settings in Stash/Bitbucket(Server) remotely. The full Bitbucket REST API is here : https://developer.atlassian.com/static/rest/bitbucket-server/4.3.1/bitbucket-rest.html

    As far as I can see there are no REST endpoints like /rest/api/1.0/projects/#{project}/repos/#{repo}/settings/pull-requests as you describe above. You may open a feature request in the Atlassian Bitbucket(Server) issue tracker to get this endpoint implemented.

  7. Log in to comment