Link releases for Ruby

Contents

Ruby apps run their source code directly, so there are no source maps to upload. Stack traces already show the right files and lines.

To link each exception to the release that produced it, create the release when you deploy and give its ID to your app. The Ruby SDK reads the ID from the POSTHOG_RELEASE_ID environment variable and sends it as $release_id on every event. This also applies to Rails apps, since posthog-rails uses the Ruby SDK.

  1. Update the SDK

    Required

    Update to posthog-ruby 3.25.0 or later:

    Terminal
    bundle update posthog-ruby

    On Rails, update posthog-rails in the same command. Each posthog-rails version depends on one exact posthog-ruby version:

    Terminal
    bundle update posthog-rails posthog-ruby

  2. Resolve the release in GitHub Actions

    Required

    Resolve the release in the workflow that deploys your app to production. Resolving creates the release if it doesn't exist yet, so skip it for pull requests, preview builds, and local development. When POSTHOG_RELEASE_ID isn't set, the SDK sends no release ID.

    Add the PostHog/resolve-release action before the step that builds your app:

    YAML
    name: Deploy
    

    on:
      push:
        branches: [main]
    

    jobs:
      deploy:
        runs-on: ubuntu-latest
        steps:
          - uses: actions/checkout@v6
    

          - name: Resolve PostHog release
            id: posthog-release
            uses: PostHog/resolve-release@v1
            with:
              api-key: ${{ secrets.POSTHOG_CLI_API_KEY }}
              project-id: ${{ vars.POSTHOG_PROJECT_ID }}
              # For EU cloud:
              # host: https://eu.posthog.com
    

          - name: Build image
            env:
              POSTHOG_RELEASE_ID: ${{ steps.posthog-release.outputs.release-id }}
            run: docker build --build-arg POSTHOG_RELEASE_ID="$POSTHOG_RELEASE_ID" --tag my-app .
    

          # Deploy the image

    The action finds the release for this commit, or creates it, and puts its ID in the release-id output. It names the release after the repository and uses the commit SHA as the version. If the same workflow also uploads source maps with that name and version, both steps use the same release.

    InputRequiredDescription
    api-keyYesPersonal API key with the error tracking write scope. Get it from your personal API key settings
    project-idYesPostHog project ID. Get it from your project settings
    hostNoPostHog host URL. Defaults to US cloud. For EU cloud, set it to https://eu.posthog.com
    release-nameNoRelease name. Defaults to the repository name
    release-versionNoRelease version. Defaults to the commit SHA

    To keep deploying when PostHog can't be reached, add continue-on-error: true and timeout-minutes: 5 to the step. If the step fails, release-id is empty, and the SDK treats an empty POSTHOG_RELEASE_ID as unset.

    See the action's README for all inputs and outputs, and for how to share one release across several jobs.

    If you don't use GitHub Actions, see without GitHub Actions.

  3. Give the release ID to your app

    Required

    The app must have POSTHOG_RELEASE_ID in its environment when it starts. The SDK reads it once, when you create the PostHog client.

    If you deploy a Docker image, turn the build argument into an environment variable. Add these lines to the stage of your Dockerfile that runs the app:

    dockerfile
    ARG POSTHOG_RELEASE_ID
    ENV POSTHOG_RELEASE_ID=$POSTHOG_RELEASE_ID

    If you don't build an image, set POSTHOG_RELEASE_ID the same way you set your app's other environment variables, with the value of the release-id output.

  4. Verify the release

    Checkpoint

    Deploy the app and capture a test exception. Then open the issue in error tracking.

    The stack trace shows the release, with its version and commit. The exception's $release_id property has the same value as the release-id output of the workflow.

Without GitHub Actions

If you deploy with another CI system or a script, resolve the release with the PostHog CLI 0.12.0 or later. Run these commands in your production deploy, from a checkout of your repository:

Terminal
npm install -g @posthog/cli


# Set these from your CI secrets
export POSTHOG_CLI_API_KEY=<personal_api_key>
export POSTHOG_CLI_PROJECT_ID=<project_id>
# For EU cloud:
# export POSTHOG_CLI_HOST=https://eu.posthog.com


export POSTHOG_RELEASE_ID=$(posthog-cli release resolve)

The command prints only the release ID. It reads the repository name and commit from Git. To choose your own, add --release-name and --release-version.

Then give POSTHOG_RELEASE_ID to your app when it starts, for example with docker build --build-arg POSTHOG_RELEASE_ID="$POSTHOG_RELEASE_ID".

Still have questions?

Was this page useful?