GitHub API (v3): Order tags by creation date

The Repositories API currently returns tags in the order they would be returned by the "git tag" command, which means they are alphabetically sorted.

The problem with sorting tags chronologically in Git is that there are two types of tags, lightweight and annotated), and for the lightweight type Git doesn't store the creation date.

The Releases/Tags UI currently sorts tags chronologically by the date of the commit to which the tag points to. This again isn't the date on which the tag itself was created, but it does establish a chronological order of things.

Adding this alternative sorting option to the API is on our feature request list.

Edit: This is now possible using the GitHub GraphQL API.

As workaround, there is a node module for this, which basically fetches the commit details of each tag: github-api-tags-full

> npm install github-api-tags-full github moment

var GitHubApi  = require('github'),
moment     = require('moment'),
githubTags = require('github-api-tags-full');

var github = new GitHubApi({
  version: '3.0.0'
});

githubTags({ user: 'golang', repo: 'go' }, github)
.then(function(tags) {
  var tagsSorted = tags.sort(byAuthorDateAsc).reverse(); // descending
  console.log(tagsSorted); // prints the array of tags sorted by their creation date
});

var byAuthorDateAsc = function(tagA, tagB) {
  return githubCompareDates(
    tagA.commit.author.date,
    tagB.commit.author.date
  );
};
var githubCompareDates = function(dateStrA, dateStrB) {
  return moment(dateStrA).diff(dateStrB);
};

With best regards

With GraphQL API v4, we can now filter tags by commit date with field: TAG_COMMIT_DATE inside orderBy. The following will perform ascending sort of tags by commit date :

{
  repository(owner: "rails", name: "rails") {
    refs(refPrefix: "refs/tags/", last: 100, orderBy: {field: TAG_COMMIT_DATE, direction: ASC}) {
      edges {
        node {
          name
          target {
            oid
            ... on Tag {
              message
              commitUrl
              tagger {
                name
                email
                date
              }
            }
          }
        }
      }
    }
  }
}

Test it in the explorer

Here, the tagger field inside target will only be filled for annotated tag & will be empty for lightweight tags.

As date property in tagger gives the creation date of the tag (for annotated tag only), it's possible to filter by creation date on the client side easily (without having to retrieve all the tags 1 by 1)

Note that available options for orderBy.field at this time are TAG_COMMIT_DATE & ALPHABETICAL (no TAG_CREATION_DATE)