Skip to content

Latest commit

 

History

History
115 lines (88 loc) · 4.47 KB

releases.md

File metadata and controls

115 lines (88 loc) · 4.47 KB
Raw

Working with Releases

Get All

To retrieve all releases for a repository:

var releases = await client.Repository.Release.GetAll("octokit", "octokit.net");
var latest = releases.Result.ElementAt(0);
Console.WriteLine(
    "The latest release is tagged at {0} and is named {1}",
    latest.TagName,
    latest.Name);

Get Latest

To retrieve the latest release for a repository:

var releases = await client.Repository.Release.GetLatest("octokit", "octokit.net");
var latest = releases.Result;
Console.WriteLine(
    "The latest release is tagged at {0} and is named {1}",
    latest.TagName,
    latest.Name);

Create

To create a new release you must have a corresponding tag in the repository. See the git-database.md docs for details.

var newRelease = new NewRelease("v1.0.0");
newRelease.Name = "Version One Point Oh";
newRelease.Body = "**This** is some *Markdown*";
newRelease.Draft = true;
newRelease.Prerelease = false;

var result = await client.Repository.Release.Create("octokit", "octokit.net", newRelease);
Console.WriteLine("Created release id {0}", result.Id);

Note that the Draft flag is used to indicate when a release should be published to the world, whereas the PreRelease flag is used to indicate whether a release is unofficial or preview release.

Generate release notes

GitHub can generate a name and body for a new release automatically, based upon merged pull requests. This is an example of automatically generated text.

var newTag = "v1.5.7";
var newRelease = new NewRelease(newTag);
newRelease.GenerateReleaseNotes = true; // Set for Name and Body to be generated.
newRelease.TargetCommitish = "main"; // Optional, can be a branch, tag, or SHA; defaults to the main branch.

Generate a discussion

Using the DiscussionCategoryName, it's possible to create a discussion linked to the upcoming release. The value must be a category that already exists in the repository. For more information, see "Managing categories for discussions in your repository."

var newTag = "v1.5.7";
var newRelease = new NewRelease(newTag);
newRelease.DiscussionCategoryName = "Announcements";

Customizing generated notes

var newTag = "v1.5.7";
var generationRequest = new GenerateReleaseNotesRequest(newTag);
generationRequest.TargetCommitish = "main"; // Optional, can be a branch, tag, or SHA; defaults to the main branch.
generationRequest.PreviousTagName = "v1.5.6"; // Optional; default is automagically determined, based on existing tags.
var releaseNotes = await client.Repository.Release.GenerateReleaseNotes("octokit", "octokit.net", generationRequest);

var newRelease = new NewRelease(newTag); // Use the same tag as before, because it now appears in generated text.
newRelease.Name = releaseNotes.Name;
newRelease.Body = releaseNotes.Body;

This feature can be customized at the repository level, by following these instructions.

Update

Once the release is ready for the public, you can apply an update to the release:

var release = client.Repository.Release.Get("octokit", "octokit.net", 1);
var updateRelease = release.ToUpdate();
updateRelease.Draft = false;
updateRelease.Name = "Version 1.0";
updateRelease.TargetCommitish = "0edef870ecd885cc6506f1e3f08341e8b87370f2" // can also be a ref
var result = await client.Repository.Release.Edit("octokit", "octokit.net", 1, updateRelease);

Upload Assets

If you have any assets to include with the release, you can upload them after creating the release:

using(var archiveContents = File.OpenRead("output.zip")) { // TODO: better sample
    var assetUpload = new ReleaseAssetUpload()
    {
         FileName = "my-cool-project-1.0.zip",
         ContentType = "application/zip",
         RawData = archiveContents
    };
    var release = client.Repository.Release.Get("octokit", "octokit.net", 1);
    var asset = await client.Repository.Release.UploadAsset(release, assetUpload);
}

TODO: are there any known limits documented to upload assets?