Get tags in a Stash commit using REST API

[Chris]

When I use the REST API to get the details for a commit:

.../rest/api/latest/projects/<project>/repos/<repo>/commits/<hash>

I get a json file that has the commit author, message, time stamp... but NO TAGS! I can see in stash that this commit does in fact have tags and I need this information.

Ok, so I tried to use the TAGS API:

.../rest/api/latest/projects/<project>/repos/<repo>/tags/<hash>

Nope, doesn't work. The only thing that you can do with tags is to add a string filter and ordering which is completely useless to me.

Is there something I'm missing? Is there a way to do this?

[Bryan Turner]

Chris,

Late to the party, but it's absolutely possible to query tags for a single commit, or set of commits, rather than streaming all the tags and looking for matches. Try something like this:

curl -u jdoe -H "Accept: application/json" -H "Content-Type: application/json"
    -X POST -d "[\"278e2fce8fd28a7fdeafca5d306957d04a52addf\"]"
    https://bitbucket.example.com/rest/tags/1.0/projects/KEY/repos/slug/tags

(The JSON array being POSTed can contain more than one commit. The response is limited to 500 tags, though, and cannot be paged, so depending on how many commits you're trying to check you may need to make multiple requests.)

The response, assuming any tags are found, will look something like this:

{
  "size":1,
  "limit":500,
  "isLastPage":true,
  "values":[{
    "id":"refs/tags/example",
    "displayId":"example",
    "type":"TAG",
    "latestCommit":"278e2fce8fd28a7fdeafca5d306957d04a52addf",
    "latestChangeset":"278e2fce8fd28a7fdeafca5d306957d04a52addf",
    "hash":null
  }],
  "start":0
}

Re: "Also it looks like it limits the number of tags you can get this info for and I couldn't see how I could iterate through to get the next lot using the existing API."

A link to our REST documentation, which explains how paging works, might have helped. But it amounts to adding a "?start=100" to the URL as a query parameter. The value to pass for "start" is returned as "nextPageStart" in the response if there are more pages available.

Hope this helps!
Bryan Turner
Atlassian Bitbucket

[Chris]

Thanks for your response, I didn't realise I could iterate using ?start=X

It's still a bit inefficient in terms of having to make multiple calls as well as then having to do hashcode matching, but at least it turns it into something that's possible to do.

[Bryan Turner]

@Chris,

Just to reiterate the first part of my response, though, you don't need to use that endpoint, or page over the results. Note the URL from my example "curl" command is "refs/tags/1.0" as opposed to "rest/api/1.0" (or "rest/api/latest"), and it's a "POST" request (taking a JSON body defining an array of 1 or more commit hashes) instead of a "GET" request. It searches directly by the commit hash (or hashes) you provide and returns up to 500 matching tags. I only provided the "?start=" comment just to clarify that it _is_ possible to page over results from the "normal" tags endpoint.

Best regards,
Bryan Turner
Atlassian Bitbucket

[Travis Pitts]

Hey Bryan,

2 years later, super super late to the party... - we are looking to do something very similar here.  Is there any type of similar endpoint on BB Cloud?

This is the doc that I found outlining anything on the tag endpoints:

https://developer.atlassian.com/bitbucket/api/2/reference/resource/repositories/%7Bworkspace%7D/%7Brepo_slug%7D/refs/tags

Any help would be much appreciated.

Thanks,

-Travis

[Bryan Turner]

@Travis Pitts

I'm not that familiar with Bitbucket Cloud (it's a wholesale different codebase/language from Bitbucket Server, despite the naming), but it looks like you can use the `q` query parameter to do match on the `target` property.

Here's an example: https://api.bitbucket.org/2.0/repositories/atlassian/amps/refs/tags?q=target+=+%22cb194337699f3e1db8cd65c7b5c7c4d47d83ba7d%22

That will return tags from our AMPS repository (it's just something that's public; there's no other specific reason why I'm using it as an example) that are tagging the cb194337699f3e1db8cd65c7b5c7c4d47d83ba7d commit.

Hope this helps!
Bryan Turner
Atlassian Bitbucket

[Travis Pitts]

@Bryan Turner 

Absolutely brilliant, this worked perfectly!! Thank you so much for the info on this!

[Daniel Groh]

How to use filterText in the tags? I want to retrieve tags only with certain pattern.

[Caterina Curti]

Hi Chris,

The way tags are retrieved is by using the  /rest/api/latest/projects/<project>/repos/<repo>/tags REST API.

For each tag this returns a JSON representation in this format:

{"id":"refs/tags/tag1",
"displayId":"tag1",
"type":"TAG",
"latestCommit":"435458d2ced9302b16d6b84707ba031832773029",
"latestChangeset":"435458d2ced9302b16d6b84707ba031832773029",
"hash":null}

This is where the commit hash is available.

If you are looking to find the tags on a commit, you should get all the tags for the repositories and then retrieve the one that matched the hash.

I see that Bitbucket Server uses a different approach to retrieve the tags for a commit by using the following request:

rest/tags/latest/projects/TP/repos/tp_rep1/tags

And then passing the commit hash in the payload.

However, this is an internal only API and should not be used in any program or script because it could be removed at any time.

It would be useful to understand what you are trying to achieve here.

Cheers,

Caterina

[Chris]

Thanks for your response. So what you are saying is that in order to get the tags associated with a specific commit hash I have to download this json info for ALL the tags in the repo and match the hashcode one by one myself? I was hoping there would be an alternative as we have quite a large repo with a LOT of tags. Also it looks like it limits the number of tags you can get this info for and I couldn't see how I could iterate through to get the next lot using the existing API.

Anyway, what I was trying to do was get the Jira issues added from an older tag to a newer tag (but first I needed to know what tags the given commits had as I parsed through them).

As an aside, I also had a go at creating Bamboo releases to work in parallel with our own build process and use the feature in there to get the Jira issues, but I had problems getting it to work due to the repo size and in any case had hell on Earth trying to get the releases to be automatically labelled with the tag for the commit (I gave up).

In the end I mostly bypassed the REST API altogether and wrote a script to parse my locally checked out copy of the repo and pattern match for anything that looks like a Jira commit code in the comments. Then later I call the Jira REST API to get more info on the Jira issue corresponding to that Jira code.