Bitbucket Cloud REST API v2.0 - Commenting on Pull Requests

[dhanielk]

Hi,

As Atlassian deprecated REST API v1.0 and will be removing it in the end of the year, how we will post Pull Request comments with API v2.0?

We have custom java app which is posting comments on Bitbucket PRs to notify users on which problems their PR failed.

Thanks,

Daniel

[seanaty · Accepted solution]

Hi Daniel,

We just deployed the docs for the remainder of the allowed HTTP methods for the pull request comments. You can see them here:

https://developer.atlassian.com/bitbucket/api/2/reference/search?q=pullrequest+comment

Let me know if you have any other questions.

[dhanielk]

Hi Sean,

Thanks for the update! I was getting quite worried that we won't be able to post comments for the Pull Requests in 2.0.

Glad to have it documented.

Regards,

Daniel

[seanaty]

No worries. It's critical functionality. Also, thanks for updating your app to the v2 APIs!

[John Camerin]

I am struggling to get this to work from my CI Server, specifically Jenkins. Jenkins has a set of credentials (hidden from me) which give it access to our BitBucket repository. I am getting a 404 back from the call to Bitbucket and need some help figuring connecting the dots. 

The call from my Jenkins pipeline

httpRequest authentication: 'bitbucket', consoleLogResponseBody: true, contentType: 'TEXT_PLAIN', httpMode: 'POST', ignoreSslErrors: true, requestBody: '{"text":"Jenkins COMMENT"}', responseHandle: 'NONE', url: changeUrl

And the values I have tried for changeUrl

https://bitbucket.org/2.0/repositories/messagegears/messsagegears-accelerator/pullrequests/2572/comments

https://bitbucket.org/repositories/messagegears/messsagegears-accelerator/pullrequests/2572/comments

https://bitbucket.org/api/repositories/messagegears/messsagegears-accelerator/pullrequests/2572/comments

PR 2572 is an open and valid pull request in our repository. Any assistance would be appreciated.

EDIT: So, as best I can tell, the Atlassian API documentation is wrong and the actual endpoint is 

https://bitbucket.org/!api/2.0/repositories/messagegears/messagegears-accelerator/pullrequests/2572/comments/

The !api and the 2.0 being somewhat undocumented, although I nearly guessed it myself.  Now, just dealing with the 400 bad request error because it doesnt like the payload.  Thanks Atlassian! 

[seanaty]

Hi @John Camerin I have a couple of suggestions.

1. The base URL you should use is https://api.bitbucket.org/2.0/ (https://bitbucket.org/api/ may work but it is deprecated. Also the other bitbucket.org URLs refer to the website and not the API--they wouldn't work).

2. The content type needs to be 'application/json' (it looks like you're using TEXT_PLAIN)

3. The content body needs to be the same "shape" as the JSON for getting comments. Here is an example:

curl https://api.bitbucket.org/2.0/repositories/<workspace>/<repo>/pullrequests/<id>/comments \
  -u myusername:mypassword \
  --request POST \
  --header 'Content-Type: application/json' \
  --data '{
    "content": {
      "raw": "first!"
    }
  }'

Hope this helps!

[John Camerin]

@seanaty 

Thanks. This did help.  Of course, what I really want to do is POST much more rich content, like a report generated in the build.  How would I post content other than plain text?  Is there a way to post some multi-line or HTML based content?

I get 400 errors back when I try and Bitbucket starts sending emails to our abuse mailbox.

EDIT: So, its taken a lot of poking and prodding and what I have learned is: 1) extreme sensitivity to where and how carriage returns and spaces are added and 2) the Bitbucket markdown is a bit of a discovery process.

Is there documentation on the Bitbucket comment markdown language?

[david.alsh]

@seanaty How would I go about supplying credentials from my pipeline?

Can I use an API token or do I have to create a user dedicated to only comment posting?

-u username:password \

[seanaty]

@david.alsh The authentication is the same as outside of a pipeline. You could use your credentials but I'd recommend making an app password. For the most security you could create a new user and use them as a bot. (Note this will be counted towards your bill depending on your plan--it's just a regular user).

Read more about different authentication here: https://developer.atlassian.com/bitbucket/api/2/reference/meta/authentication

We do run a proxy inside of the pipeline to do 2 things right now:

1. You can `git push`https://community.atlassian.com/t5/Bitbucket-Pipelines-articles/Pushing-back-to-your-repository/ba-p/958407
2. You can POST to the reports API https://support.atlassian.com/bitbucket-cloud/docs/code-insights/

This doesn't really help you, but just an FYI. You might actually be able to surface your information in a report instead of a comment.

[Prabhu Subramanian]

I can't get the create pull request comments api working with basic authentication using app passwords. It seems to work in read-only mode where the POST call is ignored and returns empty or existing comments.

Is there any other easier way to add comments from the pipeline without creating oauth applications and implementing the authentication flows to retrieve an access_token?

I have tried the proxy approach as well with no luck.

[yuri.ritvin]

Any finding on that?

[seanaty]

Unfortunately only a few API endpoints are available for use by the pipelines proxy. I don't actually have a comprehensive list but I do know that the proxy supports at least the reports API and `git push`

Other than that there should be nothing special about using the Bitbucket API inside of a pipeline (versus using the Bitbucket API outside of a pipeline). Basic auth with app passwords should work. If it's not, please provide more details (in a new thread please) to see if someone can troubleshoot.

[Aly Ibrahim]

Hi All,

I know this seems to be an old thread and you may already fixed your issues, but will put it here for reference and if somebody else is looking for Java solution for Bitbucket API V2

This java library Bitbucket-Client is build to implement bitbucket api v2

[josemonsalve2]

Hi, 

I was wondering how to connect these with token based authentication. It does not seem to support it. I tried this (which might be totally wrong):

curl https://api.bitbucket.org/2.0/repositories/{user}/{repo}/pullrequests/7/activity \
--request POST --header 'Content-Type: application/json' \
-d '{"_body":"This is a test"}' \
--header 'Authorization: Bearer "{access_token}"'

I also obtained by access token with: 

curl -X POST -u "{Key}:{secret}" https://bitbucket.org/site/oauth2/access_token \
-d grant_type=client_credentials

An I doing something wrong, or is this just not supported at all? 

Thanks for your help

Jose

[josemonsalve2]

I have figured it out. It should be added in the documentation that the only supported mode is non-POST authentication. as explained here

First, in the original post I meant to use /comments, not /activity

curl https://api.bitbucket.org/2.0/repositories/{user}/{repo}/pullrequests/7/activitycomments

Second:

Unsupported modes (ERRORS):

# This one returns: This endpoint does not support token-based authentication 
curl https://api.bitbucket.org/2.0/repositories/{user}/{repo}/pullrequests/7/comments \
--request POST --header 'Content-Type: application/json' \
-d '{"content":{"raw":"This is a test"}}' \
--header 'Authorization: Bearer "{access_token}"'

# This one returns: {"type": "error", "error": {"fields": {"access_token": "extra keys not allowed"}, "message": "Bad request"}
curl https://api.bitbucket.org/2.0/repositories/{user}/{repo}/pullrequests/7/comments \
--request POST --header 'Content-Type: application/json' \
-d '{"access_token":"{access_token}, "content":{"raw":"This is a test"}}' 

The only available option is:

curl https://api.bitbucket.org/2.0/repositories/{user}/{repo}/pullrequests/7/comments?access_token={access_token} \
--request POST --header 'Content-Type: application/json' \
-d '{"content":{"raw":"This is a test"}}' 

[seanaty]

I'm glad that you figured it out. In the future, if you can specify the specific errors you receive, that can be helpful to determining what the issue is. For example is it 403, 401, 400, 404, etc?

Also, adding the `-v` flag to curl for verbose is helpful for seeing the request/response headers. This information is also useful for troubleshooting issues, if you can paste that the next time you have an issue. (But still be sure to remove sensitive information)

Secondly, the Authorization header is supported and is the preferred method.

In the first error example you do: 

--header 'Authorization: Bearer "{access_token}"'

This looks like the double quotes "" are a part of the string, which would make things fail.

In the second error example you're passing in the the access token as a part of the body. This isn't supported. Is there are reason you attempted it this way?

[josemonsalve2]

Hi Sean,

Thanks for your response. 

I tried again without the quotes, but it gave me the same error. The only reason why I tried sending it in the body was because the preferred method did not work for me. I agree that it would be better to send this information in the header.

The error is a 403. Here is the `-v` output.

curl https://api.bitbucket.org/2.0/repositories/{user}/{repo}/pullrequests/7     --request POST     --header 'Content-Type: application/json' -v -d '{"content"{"raw":"This is a test"}}' --header 'Authorization: Bearer ****'
Note: Unnecessary use of -X or --request, POST is already inferred.

*   Trying 18.205.93.8...
* TCP_NODELAY set
* Connected to api.bitbucket.org (18.205.93.8) port 443 (#0)
* ALPN, offering h2
* ALPN, offering http/1.1
* Cipher selection: ALL:!EXPORT:!EXPORT40:!EXPORT56:!aNULL:!LOW:!RC4:@STRENGTH
* successfully set certificate verify locations:
*   CAfile: /etc/ssl/cert.pem
  CApath: none

* TLSv1.2 (OUT), TLS handshake, Client hello (1):
* TLSv1.2 (IN), TLS handshake, Server hello (2):
* TLSv1.2 (IN), TLS handshake, Certificate (11):
* TLSv1.2 (IN), TLS handshake, Server key exchange (12):
* TLSv1.2 (IN), TLS handshake, Server finished (14):
* TLSv1.2 (OUT), TLS handshake, Client key exchange (16):
* TLSv1.2 (OUT), TLS change cipher, Client hello (1):
* TLSv1.2 (OUT), TLS handshake, Finished (20):
* TLSv1.2 (IN), TLS change cipher, Client hello (1):
* TLSv1.2 (IN), TLS handshake, Finished (20):

* SSL connection using TLSv1.2 / ECDHE-ECDSA-AES128-GCM-SHA256
* ALPN, server accepted to use h2
* Server certificate:
*  subject: C=US; ST=California; L=San Francisco; O=Atlassian, Inc.; OU=Bitbucket; CN=*.bitbucket.org
*  start date: Jun 12 00:00:00 2017 GMT
*  expire date: Jun 16 12:00:00 2020 GMT
*  subjectAltName: host "api.bitbucket.org" matched cert's "*.bitbucket.org"
*  issuer: C=US; O=DigiCert Inc; OU=www.digicert.com; CN=DigiCert SHA2 High Assurance Server CA
*  SSL certificate verify ok.
* Using HTTP2, server supports multi-use
* Connection state changed (HTTP/2 confirmed)
* Copying HTTP/2 data in stream buffer to connection buffer after upgrade: len=0
* Using Stream ID: 1 (easy handle 0x7f***0)

> POST /2.0/repositories/{user}/{repo}/pullrequests/7 HTTP/2
> Host: api.bitbucket.org
> User-Agent: curl/7.54.0
> Accept: */*
> Content-Type: application/json
> Authorization: Bearer **************
> Content-Length: 35

* Connection state changed (MAX_CONCURRENT_STREAMS updated)!
* We are completely uploaded and fine
< HTTP/2 403
< server: nginx
< content-type: text/plain; charset=utf-8
< x-oauth-scopes: pullrequest:write
< strict-transport-security: max-age=31536000; includeSubDomains; preload
< date: Wed, 22 May 2019 20:27:19 GMT
< x-served-by: app-144
< x-static-version: *****
< etag: "*******"
< x-render-time: 0.0305991172791
< x-credential-type: oauth2
< x-version: ********
< x-request-count: 183
< x-frame-options: SAMEORIGIN
< content-length: 57

* Connection #0 to host api.bitbucket.org left intact
This endpoint does not support token-based authentication

[Suresh Sakhare]

Hi @dhanielk,

I am troubling to set author of the comment. Can you help me?

 {
 
 "content": {
 "raw": "Comment on PR.
 },
 "user": {
 "username": "suresh2702",
 "display_name": "Suresh Sakhare"
 "type": "user"
 }
 
 
 
 }

[Jin Wu]

hi Sureesh,

have you succeed to commet with author? if succeed, could you share your json? thanks!

[Alex Bondarev]

missing closing " in 

"raw": "Comment on PR.

[Michael Walker]

Hi Daniel,

Bitbucket cloud's API v2.0 has several resources online discussing the changes. One very useful resource is the API documentation itself which has a relatively easy search function built in. If you are looking specifically for Pull Request comments then click here. Hopefully this helps!

Cheers!

[dhanielk]

Hi Michael,

No it doesn't help at all. You can't create comments on PRs with API v2.0. At least as per documentation.

My question is about posting comments on PRs.

Thanks,

Daniel

[Michael Walker]

Hi Daniel,

I spoke to our developers about this and it appears they are putting the final tweaks on our documentation for Pull Requests right now. Please keep an eye out for in the coming days as it will be published soon. Sorry for the inconvenience!

Best Regards,

Michael

[dhanielk]

Hi Michael,

Thanks for pushing this forward.

Much appreciated,

Daniel