Configure default tasks

Learn how to use the Repository Settings API to add default tasks to pull requests in your repositories.

All sample requests in this guide include the following path parameters:

Parameter name	Description
tenantId	Your tenant ID.
starSystemId	ID of a star system (physical star system) that includes the repository.
repositoryName	Name of a repository. See supported repositories.

About default tasks

By configuring default tasks, you ensure that specific tasks are automatically added to all new pull requests. These tasks act as a checklist to guide contributors in following development best practices or completing necessary steps before merging a pull request.

The default tasks appear as pre-filled items in the Tasks section of a pull request, and contributors can mark them as completed.

Default configuration

By default, there are no tasks configured for your repositories. This configuration is defined on the Dev star system (physical star system) level and, by default, is inherited by each repository. You can create a different custom configuration of default tasks for each repository in your Dev star system (physical star system).

Note:

With the Repository Settings API, you can't modify the configuration at the Bitbucket project level.

Default task structure

The structure of a default task allows you to define a pre-configured checklist of tasks to complete that appears in applicable new pull requests. Each list item includes the following:

• Task description

  The content of the task, written in Markdown. In the description, you can define steps or guidelines that contributors should follow before merging the pull request.
  For details, see Task description.

• Source and target branch

  Specify whether the task applies globally, to all the branches, or to specific branches or branch name patterns.

To align with your team workflow, you can create a structured checklist tailored to your repository requirements.

If you want to ensure that contributors perform specific checks before merging into the release branch, you can define the following default tasks:

• Verify that all end-to-end tests have passed.
• Confirm that the change log has been updated.
• Ensure that documentation reflects these changes.

For these tasks, specify release as the target branch and ANY_REF as the source branch.

Definition

Example of a default task

{
  "id": "1",
  "scope": {
    "type": "REPOSITORY"
  },
  "sourceBranch": {
    "key": null,
    "type": "ANY_REF",
    "active": true
  },
  "targetBranch": {
    "key": "master",
    "type": "BRANCH",
    "active": true
  },
  "description": "Confirm that the change log has been updated."
}

ID and scope

Default task ID is generated automatically and is unique at a tenant level.

Each task has also a specific scope. The scope parameter has one of the following values:

• PROJECT indicates that a task is inherited and defined at the star system (physical star system) level.
• REPOSITORY indicates a custom task. Every task that you create using the Repository Settings API has this scope.

Branches

A task applies to all the pull requests created for the specified source branches to be merged to the specified target branch.

To define a branch, use the type and key parameters:

Type	Key	Description
ANY_REF	null	Applies to all branches.
BRANCH	{branchName}	Applies to the branch with the specified name. The refs/heads/ prefix is added automatically if missing.
PATTERN	Accepted wild cards: ?, *, **	Applies to every branch whose name matches the pattern. For details, see Branch patterns.
MODEL_BRANCH	production or development	Applies to all branches of the specified model.
MODEL_CATEGORY	BUGFIX, FEATURE, HOTFIX, or RELEASE	Applies to all branches of the specified category. Use uppercase letters.

Note:

The values available for MODEL_BRANCH and MODEL_CATEGORY depend on your branch configuration.

Task description

The description field defines the content of a default task and uses Markdown syntax with Bitbucket-specific extensions. Contributors will see this description in the Tasks section of pull requests and as a comment, guiding them on required actions.

Basic Text

Update the change log for this release.

Lists

Unordered list

- Verify that all end-to-end tests have passed.
- Confirm that the change log has been updated.

Ordered list

1. Verify that all end-to-end tests have passed.
2. Confirm that the change log has been updated.

Links

For details, see the [API Documentation](https://example.com/api-docs).

Formatting

**Bold**
_Italics_

For more details on the supported Markdown syntax, see the Markdown Syntax Guide.

Get configuration

To retrieve the configuration of a repository, send the following GET request:

curl -X 'GET' \
  '{baseUrl}/api/v1/tenants/{tenantId}/starsystems/{starSystemId}/repository/{repositoryName}/default-tasks' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer {access_token}'

Response contains a JSON object with all the tasks that are currently configured for this repository.

Example response

[
  {
    "id": "1",
    "scope": {
      "type": "REPOSITORY"
    },
    "sourceBranch": {
      "key": null,
      "type": "ANY_REF",
      "active": true
    },
    "targetBranch": {
      "key": "master",
      "type": "BRANCH",
      "active": true
    },
    "description": "Confirm that the change log has been updated."
  },
  {
    "id": "2",
    "scope": {
      "type": "REPOSITORY"
    },
    "sourceBranch": {
      "type": "MODEL_BRANCH",
      "active": true,
      "key": "development"
    },
    "targetBranch": {
      "type": "MODEL_CATEGORY",
      "active": true,
      "key": "BUGFIX"
    },
    "description": "Ensure that documentation reflects these changes."
  }
]

If there aren't any tasks configured for a repository, the response will be empty.

Create a default task

To create a task, send the following POST request:

curl -X 'POST' \
  '{baseUrl}/api/v1/tenants/{tenantId}/starsystems/{starSystemId}/repository/{repositoryName}/default-tasks' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {access_token}' \
  -H 'Content-Type: application/json' \
  -d '{body}'

Where {body} defines the task.

For example, to add a new default task reminding about running E2E tests for pull requests from all development branches to master, use the following:

Request body

{
  "sourceBranch": {
    "key": "development",
    "type": "MODEL_BRANCH"
  },
  "targetBranch": {
    "key": "master",
    "type": "BRANCH"
  },
  "description": "Verify that all end-to-end tests have passed."
}

For a successful request, you will receive the 200 status code and the created task with an ID and scope.

Example response

{
  "id": "1",
  "scope": {
    "type": "REPOSITORY"
  },
  "sourceBranch": {
    "key": "development",
    "type": "MODEL_BRANCH",
    "active": true
  },
  "targetBranch": {
    "key": "master",
    "type": "BRANCH",
    "active": true
  },
  "description": "Verify that all end-to-end tests have passed."
}

Modify a default task

To modify an existing task, send the following PUT request:

curl -X 'PUT' \
  '{baseUrl}/api/v1/tenants/{tenantId}/starsystems/{starSystemId}/repository/{repositoryName}/default-tasks/{defaultTaskId}' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {access_token}' \
  -H 'Content-Type: application/json' \
  -d '{body}'

Where:

• {defaultTaskId} is the ID of the task that you want to modify.
• {body} contains the modified task.

For example, to modify the task created in the previous step by updating its description to include verifying code coverage, use the following:

Request body

{
  "sourceBranch": {
    "key": "development",
    "type": "MODEL_BRANCH"
  },
  "targetBranch": {
    "key": "master",
    "type": "BRANCH"
  },
  "description": "Verify that all end-to-end tests and code coverage checks have passed."
}

For a successful request, you will receive the 200 status code and the updated task.

Example response

{
  "id": "1",
  "scope": {
    "type": "REPOSITORY"
  },
  "sourceBranch": {
    "key": "development",
    "type": "MODEL_BRANCH",
    "active": true
  },
  "targetBranch": {
    "key": "master",
    "type": "BRANCH",
    "active": true
  },
  "description": "Verify that all end-to-end tests and code coverage checks have passed."
}

Delete a default task

To delete a default task, send the following DELETE request:

curl -X 'DELETE' \
  '{baseUrl}/api/v1/tenants/{tenantId}/starsystems/{starSystemId}/repository/{repositoryName}/default-tasks/{defaultTaskId}' \
  -H 'Accept: */*' \
  -H 'Authorization: Bearer {access_token}'

Where {defaultTaskId} is the ID of the task that you want to delete.

For a successful request, you will receive the 204 status code.