6min
Releases

IntroductionThe releases API lets you declare deployment to Echoes. This information is then leveraged in multiple places:
In the Releases page, to show the timeline of releases and their content.
In ﻿Lead time, to compute the last segment of the development cycle.
In ﻿Deployment frequency, to compute the frequency without relying on tags alone.
An ﻿API key is required in order to use the Signal Releases API.
API interface

In order to reduce client complexity, the create endpoint is idempotent. Retrying a release creation with the same payload and API key will result in a single release. For an identical release, the HTTP response code is 303 and the Location header set to the URL of the release, for instance: https://api.echoeshq.com/v1/signals/releases/b84930a6-9df0-4f42-bfbb-54d3b7ed590f (with b84930a6-9df0-4f42-bfbb-54d3b7ed590f being the ID of the release).
 
POST
Params
Body Parameters
version
required
String
Version of the release.
commits
required
Array
List of the commits SHA shipped as part of the release.

Each SHA can either be the commit's hash within the pull request which introduced it, or the hash resulting from a merge into the base branch (regardless of the merging strategy used).
name
optional
String
Name of the release.
ref
optional
String
Commit SHA of the tag (for instance).
date
optional
String
Simplified extended ISO format ISO 8601, which is always 24 or 27 characters long (YYYY-MM-DDTHH:mm:ss.sssZ or ±YYYYYY-MM-DDTHH:mm:ss.sssZ, respectively). The timezone is always zero UTC offset, as denoted by the suffix "Z".

Defaults to the current time of reception of the event. 
Authorization
required
String
Bearer <YOUR_API_KEY>
deliverables
required
Array
List of the deliverables the release contains (e.g., microservice name, application name).
﻿
Usage example in GitHub CI/CDYAML
|
publish-release:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        with:
          fetch-depth: 0
        uses: actions/checkout@v2

      - name: Install packages
        run: sudo apt-get install -y libdatetime-perl

      - name: Publish release
        run: ./scripts/ci/release.sh
        env:
          ECHOESHQ_API_KEY_RELEASES: ${{ secrets.ECHOESHQ_API_KEY_RELEASES }}
publish-release:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        with:
          fetch-depth: 0
        uses: actions/checkout@v2

      - name: Install packages
        run: sudo apt-get install -y libdatetime-perl

      - name: Publish release
        run: ./scripts/ci/release.sh
        env:
          ECHOESHQ_API_KEY_RELEASES: ${{ secrets.ECHOESHQ_API_KEY_RELEASES }}
﻿
Content of the release.sh script
Shell
|
#!/bin/bash

ECHOES_API_ENDPOINT="https://api.echoeshq.com/v1/signals/releases"
API_KEY="${ECHOESHQ_API_KEY_RELEASES}"

# get the 2 latest tags
tags=( $(git describe --abbrev=0 --tags $(git rev-list --tags --max-count=2)) )

tag=${tags[0]}
prev_tag=${tags[1]}

tagdate=$(git log -1 --format=%cI "${tag}")
isoDate=$(perl -e "use Date::Parse; use DateTime; print DateTime->from_epoch(epoch => str2time('$tagdate')).Z")

url="https://github.com/__REPLACE_ME__/__REPLACE_ME__/releases/tag/${tag}"

commits=( $(git log --pretty=format:%H "${prev_tag}".."${tag}") )
commitsJSON=$(jq --compact-output --null-input '$ARGS.positional' --args "${commits[@]}")

deliverablesJSON='["mobile-app"]'

curl --silent --show-error --fail --location --request POST ${ECHOES_API_ENDPOINT} \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer '"${API_KEY}"'' \
--data-raw '{
    "name": "'"${tag}"'",
    "version": "'"${tag}"'",
    "date": "'"${isoDate}"'",
    "deliverables": '"${deliverablesJSON}"',
    "commits": '"${commitsJSON}"',
    "url": "'"${url}"'"
}'
   

#!/bin/bash

ECHOES_API_ENDPOINT="https://api.echoeshq.com/v1/signals/releases"
API_KEY="${ECHOESHQ_API_KEY_RELEASES}"

# get the 2 latest tags
tags=( $(git describe --abbrev=0 --tags $(git rev-list --tags --max-count=2)) )

tag=${tags[0]}
prev_tag=${tags[1]}

tagdate=$(git log -1 --format=%cI "${tag}")
isoDate=$(perl -e "use Date::Parse; use DateTime; print DateTime->from_epoch(epoch => str2time('$tagdate')).Z")

url="https://github.com/__REPLACE_ME__/__REPLACE_ME__/releases/tag/${tag}"

commits=( $(git log --pretty=format:%H "${prev_tag}".."${tag}") )
commitsJSON=$(jq --compact-output --null-input '$ARGS.positional' --args "${commits[@]}")

deliverablesJSON='["mobile-app"]'

curl --silent --show-error --fail --location --request POST ${ECHOES_API_ENDPOINT} \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer '"${API_KEY}"'' \
--data-raw '{
    "name": "'"${tag}"'",
    "version": "'"${tag}"'",
    "date": "'"${isoDate}"'",
    "deliverables": '"${deliverablesJSON}"',
    "commits": '"${commitsJSON}"',
    "url": "'"${url}"'"
}'
   
﻿
﻿
Patch a Release status by ID
PATCH
Params
Path Params
id
required
String
ID of the release to change the status for.
Body Parameters
status
required
String
The status of the Release either `failure` or `success`.
﻿
﻿
Updated 09 Mar 2023
Did this page help you?
Yes
UP NEXT
Data exports
Docs powered by archbee
Create release