Report Releases and Deployments from GitHub Actions

What the action records

The action always registers the product version with its changelog. If you also pass customer-alias and environment, it records an installation of that version for the customer. The dashboard and the customer's About page then show which version runs in which environment.

Registering the same version again only updates its changelog. Installations are a history, so every run with customer-alias and environment adds a new record, including reruns of the workflow.

Set up the GitHub Action in 3 steps

The action is published in GitHub Marketplace as abouttheapp/sync. Its source code and all inputs are in the abouttheapp/sync repository.

1. 1

   Create a CI/CD token

   In the AboutTheApp dashboard, open the user menu, choose Account and generate a token in the CI/CD section. Only the account owner can do this and the token is shown only once.

2. 2

   Store it as a secret

   Save the token in the repository as the ABOUTTHEAPP_TOKEN Actions secret. One token works for all products in the account and generating a new one invalidates the old one.

3. 3

   Add the step after your deployment

   Put abouttheapp/sync@v1 after the steps that deploy your app, so only successful deployments are recorded. The product and the customer must already exist in AboutTheApp and the customer needs an alias.

name: Release

on:
  push:
    tags: ["v*"]

jobs:
  release:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v5
        with:
          fetch-depth: 0

      - name: Resolve release metadata
        id: release
        run: |
          echo "version=${GITHUB_REF_NAME#v}" >> "$GITHUB_OUTPUT"
          echo "previous-tag=$(git describe --tags --match 'v*' --abbrev=0 HEAD^ 2>/dev/null || true)" >> "$GITHUB_OUTPUT"

      # ... your build and deploy steps ...

      - name: Report release to AboutTheApp
        uses: abouttheapp/sync@v1
        with:
          token: ${{ secrets.ABOUTTHEAPP_TOKEN }}
          alias: my-app
          version: ${{ steps.release.outputs.version }}
          changelog-source: git-log
          changelog-since: ${{ steps.release.outputs.previous-tag }}
          version-visibility: public
          customer-alias: acme
          environment: production

Release notes from Git history, a file or text

If you set changelog-source: git-log, the release notes are built from the commits since the tag in changelog-since. The checkout then needs fetch-depth: 0. If you set changelog-source: file, the action uses the section of a Keep a Changelog file whose heading matches the version, for example ## [1.2.3]. You can also pass the text directly in the changelog input.

New versions are private by default. Add version-visibility: public to show them on the public About page. If you're not sure what to write in them, use the release notes template.

Record only deployments that actually run

If you set verify-url, the action first waits until the deployed app reports the new version, for example in a version.json file. If the app still reports another version when verify-timeout runs out (300 seconds by default), the step fails and nothing is recorded.

The URL must answer without authentication with JSON such as {"version": "1.2.3"} or plain text whose first line is the version. If your app doesn't expose its version yet, read how to display the app version.

      - name: Report release to AboutTheApp
        uses: abouttheapp/sync@v1
        with:
          token: ${{ secrets.ABOUTTHEAPP_TOKEN }}
          alias: my-app
          version: 1.2.3
          customer-alias: acme
          environment: production
          verify-url: https://app.example.com/version.json

Frequently asked questions