API support for listing tags and fetching tag details

[stephenc]

Description

The API currently exposes details of branches and pull requests but does not allow discovering tags.

The minimum support that I would like to see:

• A way to get a list of all tags in a repository, e.g. /api/v1/repos/${repoOwner}/${repoName}/tags
• A way to get a specific tag, e.g. /api/v1/repos/${repoOwner}/${repoName}/tags/${tagName}
• Push event notification on creation of tags (if not already present)

The tag JSON object should probably have the following structure:

• lightweight tags (i.e. where the tag refers to a commit):

  {
    name: "v1.0.0",
    commit: {
      id: "...",
      message: "...",
      url: "...",
      author: {
        name: "...",
        email: "...",
        username: "..."
      },
      committer: {
        name: "...",
        email: "...",
        username: "..."
      },
      verification: {
        verified: false,
        reason: "gpg.error.not_signed_commit",
        signature: "",
        payload: ""
      },
      timestamp: "2017-08-31T19:26:04Z"
    }
  }
  

• annotated tags (i.e. where the tag is an object referencing the commit):

  {
    name: "v1.0.0",
    tag: {
      id: "...",
      message: "...",
      url: "...",
      author: {
        name: "...",
        email: "...",
        username: "..."
      },
      committer: {
        name: "...",
        email: "...",
        username: "..."
      },
      verification: {
        verified: false,
        reason: "gpg.error.not_signed_commit",
        signature: "",
        payload: ""
      },
      timestamp: "2017-08-31T19:26:04Z",
      commit: {
        id: "...",
        message: "...",
        url: "...",
        author: {
          name: "...",
          email: "...",
          username: "..."
        },
        committer: {
          name: "...",
          email: "...",
          username: "..."
        },
        verification: {
          verified: false,
          reason: "gpg.error.not_signed_commit",
          signature: "",
          payload: ""
        },
        timestamp: "2017-08-31T19:26:04Z"
      }
    }
  }
  

[bkcsoft]

https://developer.github.com/v3/git/tags/

[stephenc]

note that on github's api, it is undocumented, but GET /repos/:owner/:repo/git/tags will return a paged list of tags.

as long as there is a way to get a list of tags, get a tag by name and get push notification of tags then I can implement jenkinsci/gitea-plugin#6

[stephenc]

@lafriks any ETA?

[lafriks]

sorry, currently no one is on this at the moment but we are one step closer to this as all tag data are already in database so this should be easy enough to implement.

[tgulacsi]

This got serious: the new vgo experiment needs an API to parse versions (https://godoc.org/golang.org/x/vgo/vendor/cmd/go/internal/modfetch#Repo), so this will be required.

Any directions? Which API endpoint should we start copying for this?

[lunny]

@tgulacsi vgo will be released at least about six month I think. Maybe we have enough time to resolve this issue if someone would like to send a PR.

[tgulacsi]

I'd like to help, just point me in the right direction. An API endpoint to copy would be a good start. Lunny Xiao <notifications@github.com> ezt írta (időpont: 2018. febr. 25., V, 14:45):

…

@tgulacsi <https://github.com/tgulacsi> vgo will be released at least about six month I think. Maybe we have enough time to resolve this issue if someone would like to send a PR. — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#2738 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AAPoSpWNHY64xTab2yI95yxNAujX8mndks5tYWQHgaJpZM4P-fRm> .

[sapk]

You can look at merged PR related to API : https://github.com/go-gitea/gitea/pulls?utf8=%E2%9C%93&q=is%3Apr+label%3Akind%2Fapi+is%3Aclosed+

[sapk]

For example a simple API added endpoint : #2047
You may need to update the sdk (https://github.com/go-gitea/go-sdk) before like in #1668 with go-gitea/go-sdk#56

[tgulacsi]

PTAL on https://github.com/tgulacsi/gitea/tree/api-tags esp. https://github.com/tgulacsi/gitea/blob/api-tags/models/tag.go - it compiles, but that's all. I don't know how should I test it, or whether it is moderately acceptable at all.
What about the paths? (/repos/:id/tags)
Now it is only to list tags, as Release already embodies a tag, so it is not clear how these two should live together...

[sapk]

For design of path and response format we generally try to follow github format for compat. For testing try to write integrations tests like in #2047 and try to run them with https://github.com/go-gitea/gitea/tree/master/integrations#integrations-tests. When you start to have something working submit a PR so that we can review it.

[tgulacsi]

github.com/gomods/athens works as a GOPROXY and no need for the go mod specific API. Stephen Connolly <notifications@github.com> ezt írta (időpont: 2018. szept. 4., K, 22:55):

…

Ping! — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#2738 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AAPoSvspSzxosW0ktJpIp0nn09u9iwgeks5uXujWgaJpZM4P-fRm> .

[stephenc]

@thulacsi I suspect you don’t understand what this ticket is looking for as your answer does not make any sense to me. What has GOPROXY got to do with an API exposed in the gitea webapp that allows listing the git tags in a git repo hosted on a gitea server?

[lunny]

@stephenc so, but why close this one?

[stephenc]

@lunny sorry hit wrong button... thanks for pointing out

[lafriks]

@stephenc I started implementing with GitHub compatible Git Refs API routes and objects

[lafriks]

Tag list is now implemented using refs API, still missing getting tags details

[lafriks]

Getting tag details will be in 1.8.0, so I'm moving issue to that milestone

[lunny]

@lafriks since there is no PR for this, let's move this to 1.9.0

[conradoqg]

Is someone working on this?

[stephenc]

I hope so because the fully polished Jenkins plugin is dependent on this

[lafriks]

Listing is done, I'm working on details

[richmahn]

@stephenc Is it wanting /api/v1/repos/${repoOwner}/${repoName}/tags/${tagName} or /api/v1/repos/${repoOwner}/${repoName}/git/tags/${tagName} ? GitHub has /repos/${repoOwner}/${repoName}/tags and then you have to change /tags to /git/tags/{$tagSHA}. There is also /git/refs and /git/refs/tags/<$tagSHA> so wondering what exactly Jenkins is looking for.

[richmahn]

I'm now working on the details for tags.

[stephenc]

So right now we have this API to list the tags:

The /repos/{owner}/{repo}/git/refs/{ref} path doesn't return an object with the details we require

Namely it doesn't supply the details of the timestamp of the tag object or enable differentiation between annotated tags and lightweight tags.

If I look at the GitHub API, https://developer.github.com/v3/git/tags/ provides the details we need. I think what you want is to implement a route equivalent to the github one, namely /repos/{owner}/{repo}/git/tags/{tag}. This route would only support annotated tag objects, so if it returns a failure then we can conclude that the object is a lightweight tag!

Once we have /repos/{owner}/{repo}/git/tags/{tag} then we are good.

Now having said all that, if I wasn't interested in matching closely the github api, then I might separate the routes differently and have the tags route return the rich objects... but as I understand it, mirroring the GitHub API structure is valued by Gitea, so in that case /repos/{owner}/{repo}/git/tags/{tag} is all that remains

[richmahn]

@stephenc That's for your response! Actually just figured out myself, before reading your reply, that git/refs/tags does not distinguish between lightweight (commit) tags and annotated (tag) tags. So I have already change that in my work on this.

[richmahn]

@stephenc See my PR above. Should have everything you specified, with /git/tags/{sha} only working for annotated tags.