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.