Atly Apps
Marketplace
Atly Apps/Apps/Pull Request Labels/Documentation

Documentation

Learn how to label pull requests, require labels before a merge, and automate labelling from Pipelines or an agent.

01Getting started

Pull Request Labels for Bitbucket Cloud lets you add labels to pull requests, require specific labels before a merge is allowed, and manage labels from a comment — handy for a pipeline step or an agent.

i

Before you begin: install the app from the Atlassian Marketplace. Once installed, a Labels panel appears automatically on every pull request — no configuration required.

Every label has a name and a colour. Labels are defined once per repository and can be reused across every pull request — manage the full list from the repository's Labels page in the sidebar.

02Labelling a pull request

Open any pull request and find the Labels panel on the overview tab. Click + Add label to pick an existing label, or type a new name to create one.

To remove a label, click it and choose Remove label from the popup.

03Requiring labels before merge

To stop pull requests merging without certain labels, open Repository settings → Pull request labels and add one or more labels to the Required labels list.

  1. Open the repository, then go to Repository settings.
  2. Select Pull request labels in the left sidebar.
  3. Add each label that should be required — these appear as a merge check on every pull request in the repository.

The Has required label(s) merge check runs when a pull request is merged or a commit is pushed to it, and blocks the merge while any required label is missing — listing exactly which ones.

i

Deleting a label that's marked as required needs repository admin access, since it also removes it from the required list.

04Comment commands

Labels can also be added or removed by posting a comment on a pull request — useful from a Bitbucket Pipelines step, or an agent that only has comment access.

Pull request comment
/label add bug, needs review
/label remove wip

Each command goes on its own line, with multiple labels separated by commas. Labels must already exist in the repository, and names are matched regardless of case. The app replies on the comment with what changed.

From a Bitbucket Pipelines step, post the comment with a repository access token:

bash
curl -X POST \
  -H "Authorization: Bearer $LABELS_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  "https://api.bitbucket.org/2.0/repositories/$BITBUCKET_REPO_FULL_NAME/pullrequests/$BITBUCKET_PR_ID/comments" \
  -d '{"content": {"raw": "/label add deployed"}}'
i

The commenter needs write access to the repository — the app checks permissions on every command, so a read-only token or user can't add or remove labels this way.

05FAQ

Is this app available yet?

Pull Request Labels is in final testing ahead of its Atlassian Marketplace launch. The features on this page are final — only the Marketplace listing is pending.

Does the required-labels check affect pull requests I already have open?

The merge check only runs on merge and on new commits, so an open pull request is only checked the next time it's pushed to or merged — not retroactively.

Can I see which open pull requests use a given label?

Yes. The repository's Pull request labels page lists every label with its description and a count of open pull requests — click the count to see them.

Who can add or remove labels from a comment?

Anyone with write access to the repository, including a repository access token used from a Bitbucket Pipelines step.

Which Bitbucket plans does this work with?

Pull Request Labels works with all Bitbucket Cloud plans, including Free, Standard and Premium. It is not compatible with Bitbucket Data Center or Server.

Is my data sent to Atly's servers?

No. Pull Request Labels is built on Atlassian Forge and runs entirely on Atlassian's own infrastructure. Your content is never sent to or stored on Atly's servers.