How to configure releases in Athenian

Fully match your release workflow with an automatic release configuration and a custom release configuration method.

Paul Bleicher avatar
Written by Paul Bleicher
Updated over a week ago

The Release Cycle Time is the elapsed time between a PR being merged and actually being released. Athenian offers two release configuration methods: an automatic release configuration and a custom release configuration to fully match your release workflow.

Automatic release configuration

By default, Athenian checks if a repository has a release tag on GitHub and will consider it as the release. Athenian takes the merge in the default branch as the release if no tag is detected.

The diagram below summarizes how Athenian automatically configures the release event once a repository is connected:

Custom release configuration

Athenian allows you to customize the release configurations for your repositories completely.

Three different options are available:

  1. Branch

  2. Tag

  3. Event (API Call)

Go to your release settings to customize the settings for each of your repositories. Once you’ve updated your release settings, all metrics based on it, such as Lead Time, will update. You’ll also see an update of the “released” label in the pull requests table. Continue reading below on when to use each of the 3 options available.

Configuring releases based on branches

The default branch for releases will often be the ‘master’ or ‘main’ branch. GitHub allows you to define your default branch to any branch name you like.

To change the release branch, simply add the name of your branch in the box. In the example below, the release event will be triggered when a merge happens on the production branch.

But you can also use regular expressions to match multiple branch names. In the example below, the release event will be triggered when a merge happens on a branch name starting with ‘release-’. Please note that the regular expression for this is ‘release-.*’ (don’t forget the . before the *).

Configuring releases based on tag

To configure releases based on tags, select the Tag option. The default option is to look at any Tag.

You can also use regular expressions to match custom Tags automatically. In the example below, the release event will be triggered when Athenian detects a tag that starts with ‘release’. Please note that the regular expression for this is ‘release-.*’ (don’t forget the . before the *).

Configuring releases based on Events (API Call)

The Events-based method allows you to configure releases based on an event sent to Athenian via our API. This is the most flexible option and will enable you to match more complex release workflows. For instance, you can include this API call at the end of your deployment script to production to accurately match when work has been released to the end-user.

Step 1. Create an Athenian API key (once-off)

We invite you to generate a persistent API key. To do so:

  1. Get your Account ID & bearer token by visiting https://app.athenian.co/bearer. You need to wait a few seconds for the token to load.

  2. Then generate your API key using the following call.
    curl -H "Authorization: Bearer <bearer token>" -d '{"account": <account id>, "name": "My Persistent API Token"}' https://api.athenian.co/v1/token/create -H 'Content-Type: application/json'

  3. Once generated, save your key as you won't be able to see it again. However, you can generate as many keys as you like or invalidate them (see our API spec here on how to invalidate a token).

Step 2. Notify Athenian of a release

You can now use the following API call to notify Athenian about a release in, for instance, your deployment script.

curl -H "X-API-Key: <api key>" https://api.athenian.co/v1/events/releases -d '[{"repository": "github.com/<github org>/<repository>", "commit": "<commit hash>", "author": "<release author>", "name": "<release name>", "url": "<release url>"}]' --header 'Content-Type: application/json'

Please note that only the repository and commit fields are mandatory fields. You can omit the author, name of the release, and URL. These 3 fields are valuable to add as they will show in the release table in the product when filled out.

An example of a minimal request is:

curl -H "X-API-Key: CiQAx7JIGwVntSOTZPoDbL4qwNg2Fif+D3guBml7Ihn13r5EL0cSMQCOc0KbHWnuLuCMrbugFqAM3OzbjXtSxrAquIs5mMe7G93XUUQ6p+CR65+7xXcXxr=" https://api.athenian.co/v1/events/releases -d '[{"repository": "github.com/xyzcorp/web-app", "commit": "5e144da95ffe675ac0ac0ddf0ba9c9c88a416f01"}]' --header 'Content-Type: application/json'

Please refer to the API documentation for more details on this endpoint: https://api.athenian.co/v1/ui/#/events/notify_releases

Step 3. [optional] Backfill release events from the past

If you want to notify Athenian about your past releases, you can provide us with an export from your tooling. This can be a text file, CSV, JSON, etc. We’ll apply them for you. If you’re feeling adventurous, you can also use the API to do this yourself but make sure to POST the release events from old to new.

Step 4. Change the release settings of your repository

As a final step to your release settings, select the Event-based method for the repository you have set up.

Congratulations! Your Athenian account now takes into account your release workflow.

Need help? Just send us a message.

Did this answer your question?