Achieve Effortless GitHub Releases With a New Plugin for TeamCity

Dmitrii Korovin

GitHub releases are fantastic for distributing your open-source projects, as they let you turn any code revision into ready-to-go assets with a detailed version history. What makes them particularly popular, though, is that they give users a proper Download button (because not everyone dreams of compiling source code).

In TeamCity, the traditional approach for publishing GitHub releases is to run custom scripts via the Command Line build step. While certainly viable, this approach comes with a catch: You need to write and maintain that script and handle authentication on your own. Even more frustrating, TeamCity already has a perfectly good authentication token tucked away in your VCS root – an authentication token that you cannot directly reuse.

The new GitHub Releases Support plugin aims to eliminate this inconvenience once and for all. No more guesswork, no more custom scripting. With just a few clicks, you can publish your builds as GitHub releases and focus on shipping features instead of wrangling scripts.

Install

This is an unbundled plugin, which means you’ll need to download it from our Marketplace and install it on your server. To do this, click the Get button in the top right corner of the plugin page, or go directly to the Admin | Plugins page of your TeamCity server and click Browse plugins repository.

See also: Installing Additional Plugins

Configure

Once the plugin is installed, you can add the GitHub Release step to build configurations as you would any other build step.

Here’s a quick overview of the key settings:

• Release Repository – The GitHub repository where your release will be published. TeamCity automatically lists repositories based on the VCS roots attached to the parent build configuration.
• Release Tag – The unique tag to label your new release. Use a parameter reference (%teamcity_parameter_name%) to fetch this value from a TeamCity parameter. You can provide this value before the build starts (via the Run Custom Build dialog) or calculate it during a build.
• Release Title and Release Notes –  Additional details that are optional, but highly recommended. Your users will appreciate a concise description and some context. You can import the content for these fields from TeamCity parameters and let GitHub append its own auto-generated notes to your custom ones.
• Asset Paths – Files you want to publish as release assets. If you’ve run the build before, you can simply browse and select files using the folder browser instead of typing paths manually.
• Release Options – A field where you can mark the release as a draft or pre-release, or flag it as the latest release.

The plugin supports multiple authentication methods, seen in the Commit Status Publisher or similar TeamCity build features.

• Use VCS root credentials — Reuse the same authentication method your VCS root already uses.
• Access Token — Provide a personal GitHub access token, issued on your GitHub profile settings page.
• GitHub App access token — Use an existing GitHub App token, or create a new one, directly from TeamCity. See this documentation article for more information.

Kotlin DSL

For those who enjoy configuration as code, here’s how the step settings look in the Kotlin DSL:

gitHubRelease {
    name = "Publish release"
    targetVcsRootId = "${myVcsRoot.id}"
    githubUrl = "https://api.github.com"
    tagName = "v%release.version.number%" // Supports parameter references
    releaseName = "Release %release.version.number%" // Optional, uses 'tagName' if omitted
    releaseNotes = """
            ## Changelog:
            %release.changelist%
        """.trimIndent()

    // Optional, specified files will be uploaded as release assets.
    // Paths are relative to the checkout directory, files should be present when this step runs
    assetPaths="""
            library/build/libs/library-1.0-SNAPSHOT.jar
            app/build/libs/app-1.0-SNAPSHOT.jar
        """.trimIndent()

    latest = true // Optional, labels the published release as the latest one
    authType = vcsRoot()
}

Run

Once everything is set up, hit that big blue Run button.

When the build finishes, you’ll see a Release Details section on the Build Results page. From there, click the provided link to open your freshly minted GitHub release. (Cue a sigh of relief, and maybe a small celebration.)

Your Feedback Matters!

The GitHub Releases Support plugin may not come bundled in TeamCity, but we hope you find it as handy as many of the bundled ones.

Have any ideas or requests? Would you like to give our developers a virtual high-five? Drop by JetBrains Marketplace to leave a review, or get in touch through our regular feedback channels. We listen closely to user requests and always value your feedback.

Subscribe to TeamCity Blog updates

Subscribe form

By submitting this form, I agree to the JetBrains Privacy Policy Notification icon

By submitting this form, I agree that JetBrains s.r.o. ("JetBrains") may use my name, email address, and location data to send me newsletters, including commercial communications, and to process my personal data for this purpose. I agree that JetBrains may process said data using third-party services for this purpose in accordance with the JetBrains Privacy Policy. I understand that I can revoke this consent at any time in my profile. In addition, an unsubscribe link is included in each email.

Submit

Thanks, we've got you!