Octokit and the Content of Releases

I started out my series on Octokit by defining a goal; to use GitHub repository history to build a basic summary of changes contained in a release. In order to do this, we need to define what a release is and then determine how we get the pertinent information to say what changes that release contains.

At a basic level, a release is a tagged point in the git repository. GitHub takes this one step further by making a release a first class concept as a lightweight git tag with additional attributes like a title and release notes. Octokit even allows first class access to GitHub releases in a repository, like so:

var releases = await gitHubClient.Release.GetAll("RepositoryOwner", "RepositoryName");

Great! With a little extra code, we can determine which release was the latest and then get all the commits in that release.

var latestRelease = releases.MaxBy(r => r.CreatedAt);

var commitRequest = new CommitRequest
{
    Until = latestRelease.CreatedAt,
    Sha = latest.TagName
};
var commits = await github.Repository.Commits.GetAll("RepositoryOwner", "RepositoryName", commitRequest);

In the above code, we use MoreLinq to get the most recent release and then request all the commits in the repository on the same branch as that release up until the date the release was created. We request these commits using a `CommitRequest` object that specifies the query parameters. In this case, we want all the commits until the date of the release for the tag on which the release was made¹. Of course, this will include everything ever done in that branch since the beginning of time, which is a bit of information overload. What we really want are the commits since the previous release.

var mostRecentTwoReleases= releases
    .OrderByDescending(r => r.CreatedAt)
    .Take(2)
    .ToArray();

var commitRequest = new CommitRequest
{
    Until = mostRecentTwoReleases[0].CreatedAt,
    Sha = mostRecentTwoReleases[0].TagName,
    Since = mostRecentTwoReleases[1].CreatedAt
};
var commits = await github.Repository.Commits.GetAll("RepositoryOwner", "RepositoryName", commitRequest);

Now we have taken the releases and used their `CreatedAt` dates to determine the most recent two and used the previous release date to set the `Since` date in our request. However, this code still has a flaw; we never said what branch the releases should be from. For all we know, the most recent two releases are on entirely different branches. To fix that, we need to filter the releases to just the branch we want.

var mostRecentTwoReleases= releases
    .Where(r => r.TargetCommitish = "myBranch")
    .OrderByDescending(r => r.CreatedAt)
    .Take(2)
    .ToArray();

var commitRequest = new CommitRequest
{
    Until = mostRecentTwoReleases[0].CreatedAt,
    Sha = mostRecentTwoReleases[0].TagName,
    Since = mostRecentTwoReleases[1].CreatedAt
};
var commits = await github.Repository.Commits.GetAll("RepositoryOwner", "RepositoryName", commitRequest);

The highlighted line is where we filter on the appropriate branch (it took some investigation to discover that the `TargetCommitish` property of a release is its branch name). We now have just the commits for the release branch we care about between the most recent release and the one before it.

In the next post, we will look at reducing the noise in the commit history using pull requests. Until then, thank you for stopping by and don't forget to leave a comment.

1. The `Sha` property of the `CommitRequest` can be either a commit hash or branch/tag name [↩]