GitHub action agent

This page contains the setup guide for the RelativeCI agent v5 beta. Go to RelativeCI agent v4 to read the setup guide for the current stable version.

Step 1. Output bundle stats JSON file

Follow the steps on Output bundle stats JSON file guide.

Step 2. Configure GitHub action

Depending on your GitHub workflow and project requirements, you can use one of the following scenarios to configure relative-ci/agent-action:

`push` / `pull_request`

One-step setup for private or small projects

`workflow_run`

Two-step workflow recommended for open-source projects, projects that use forks, or teams with increased security requirements.

`push` event

Add relative-ci/agent-action after your build step (the build step outputs the bundle stats based on the Step 1. setup).

.github/workflow/build.yml

name: Build

on:
  push:

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 'latest'

      # Install dependencies
      - run: npm ci

      # Build and output bundle stats to webpack-stats.json
      - run: npm run build -- --json webpack-stats.json

      # Send bundle stats and build information to RelativeCI
      - name: Send bundle stats to RelativeCI
        uses: relative-ci/agent-action@v3.0.0-beta
        with:
          webpackStatsFile: ./webpack-stats.json
          key: ${{ secrets.RELATIVE_CI_KEY }}

ExampleGitHub action (push event)

`pull_request` event

Add relative-ci/agent-action after your build step(the build step outputs the bundle stats based on the Step 1. setup).

.github/workflow/build.yml

name: Build

on:
  push:
    branches:
      - master
  pull_request:

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 'latest'

      # Install dependencies
      - run: npm ci

      # Build and output bundle stats to webpack-stats.json
      - run: npm run build -- --json webpack-stats.json

      # Send bundle stats and build information to RelativeCI
      - name: Send bundle stats to RelativeCI
        uses: relative-ci/agent-action@v3.0.0-beta
        with:
          webpackStatsFile: ./webpack-stats.json
          key: ${{ secrets.RELATIVE_CI_KEY }}

ExampleGitHub action (pull_request event)

Build information

When the action runs during the pull_request event, GitHub action checks out and reports the merge commit information:

GITHUB_REF='refs/pull/123/merge'
GITHUB_SHA='Merge #abcd124 into #abcd123'

In order to collect the information for the commit that triggered the pull request, the agent extracts the commit id from the GitHub action event data (event.json).

To extract the commit message, you can use one of the following methods:

Extract commit message from git history

To collect the corresponding commit message from the git history, configure the GitHub action to checkout a range of commits that includes the commit that triggered the pull request:

.github/workflow/build.yml

name: Build

on:
  push:
    branches:
      - master
  pull_request:

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          # Fetch latest 2 commits to allow relative-ci/agent-action
          # to lookup the pull request corresponding commit message
          fetch-depth: 2

      - uses: actions/setup-node@v4
        with:
          node-version: 'latest'

      # Install dependencies
      - run: npm ci

      # Build and output bundle stats to webpack-stats.json
      - run: npm run build -- --json webpack-stats.json

      # Send bundle stats and build information to RelativeCI
      - name: Send bundle stats to RelativeCI
        uses: relative-ci/agent-action@v3.0.0-beta
        with:
          webpackStatsFile: ./webpack-stats.json
          key: ${{ secrets.RELATIVE_CI_KEY }}

In case the agent fails to look up the commit that triggered the pull request, consider increasing the fetch-depth value.

Extract commit message using GitHub API

To collect the corresponding commit message using the GitHub API, add a step to fetch the commit information and set the RELATIVE_CI_COMMIT_MESSAGE environment variable:

.github/workflow/build.yml

name: Build

on:
  push:
    branches:
      - master
  pull_request:

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-node@v4
        with:
          node-version: 'latest'

      # Install dependencies
      - run: npm ci

      # Build and output bundle stats to webpack-stats.json
      - run: npm run build -- --json webpack-stats.json

      # Read pull request commit message
      - name: Read pull request commit message
        id: pull-request-commit-message
        run: |
          # Get the pull request commit's SHA/ID from the event data file
          COMMIT_SHA=$(cat $GITHUB_EVENT_PATH | jq -r ".pull_request.head.sha")

          # Fetch commit data from the GitHub API and pick the commit message value
          COMMIT_MESSAGE=$(gh api /repos/$GITHUB_REPOSITORY/commits/$COMMIT_SHA --jq .commit.message)

          # Set output
          echo "commit-message=$COMMIT_MESSAGE" > $GITHUB_OUTPUT
        env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}

      # Send bundle stats and build information to RelativeCI
      - name: Send bundle stats to RelativeCI
        uses: relative-ci/agent-action@v3.0.0-beta
        with:
          webpackStatsFile: ./webpack-stats.json
          key: ${{ secrets.RELATIVE_CI_KEY }}
        env:
          RELATIVE_CI_COMMIT_MESSAGE: ${{ steps.pull-request-commit-message.outputs.commit-message }}

ExampleGitHub action (pull_request event)

`workflow_run` event

About workflows triggered by forked repositories or insecure workflows (dependabot updates)

GitHub actions do not share secrets with workflows triggered by forked repositories or insecure workflows. To safely run action steps that require access to secrets, GitHub recommends running the workflow on workflow_run event.

When the workflow is triggered by the workflow_run event, the jobs are running in the context of the base branch, making it safe to access the repository secrets. relative-ci/agent-action collects the build information from the event data (event.json) and the bundle stats from the artifacts uploaded during the build workflow(build.yaml)

Workflow 1: Build and upload bundle stats artifacts

Build and upload bundle stats artifact using relative-ci/agent-upload-artifact-action:

The action uses upload-artifact@v4+, which is not currently supported on GitHub Enterprise Server yet. If you are using GitHub Enterprise Server, you must use relative-ci/agent-upload-artifact-action@v1.

.github/workflows/build.yaml

name: Build

on:
  push:
    branches:
      - master
  pull_request:

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 'latest'

      # Install dependencies
      - run: npm ci

      # Build and output bundle stats
      - run: npm run build -- --json webpack-stats.json

      # Upload bundle stats artifact to use on relative-ci.yaml workflow
      - name: Upload webpack stats artifact
        uses: relative-ci/agent-upload-artifact-action@v2
        with:
          webpackStatsFile: ./webpack-stats.json

Workflow 2. Send bundle stats and build information to RelativeCI

Create a new workflow triggered by the previous build workflow (Build) to download the bundle stats artifact and send it to RelativeCI. The workflow runs securely in the default branch context(ex: main). relative-ci/agent-action uses the build information (commit, message, branch) corresponding to the commit that triggered the Build workflow.

.github/workflows/relative-ci.yaml

name: RelativeCI

on:
  workflow_run:
    workflows: ["Build"]
    types:
      - completed

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Send bundle stats and build information to RelativeCI
        uses: relative-ci/agent-action@v3.0.0-beta
        with:
          key: ${{ secrets.RELATIVE_CI_KEY }}
          token: ${{ secrets.GITHUB_TOKEN }}

ExampleGitHub action (forked repository pull_request event)

Secrets

`RELATIVE_CI_KEY` - required

`RELATIVE_CI_ENDPOINT` - required for RelativeCI Enterprise Cloud/Server

Inputs

View action.yml

key (required): RelativeCI API project key
token (required on workflow_run events): GitHub API token - used to fetch the bundle stats artifact.
webpackStatsFile (required on push/pull_request events): Path to webpack stats file
artifactName (default relative-ci-artifacts on workflow_run): The name of the artifact uploaded during the build workflow that contains the bundle stats
endpoint (required for Enterprise Cloud customers)
slug (default GITHUB_REPOSITORY): Your project slug
includeCommitMessage (default true): Get current commit message (git log -1 --pretty=%B) and send it to RelativeCI as part of the build information
debug (default false): Enable agent debug output

Monorepo

If you are using a monorepo setup and need to send the build information and the stats for multiple projects, use different API keys and stat files for each project.

Example for `push` / `pull_request` events

.github/workflow/build.yml

# ...
      # Project A - Send bundle stats and build information to RelativeCI
      - name: Project A - Send bundle stats to RelativeCI
        uses: relative-ci/agent-action@v3.0.0-beta
        with:
          webpackStatsFile: ./project-a/webpack-stats.json
          key: ${{ secrets.RELATIVE_CI_KEY_PROJECT_A }}
          token: ${{ secrets.GITHUB_TOKEN }}

      # Project B - Send bundle stats and build information to RelativeCI
      - name: Project B - Send bundle stats to RelativeCI
        uses: relative-ci/agent-action@v3.0.0-beta
        with:
          webpackStatsFile: ./project-b/webpack-stats.json
          key: ${{ secrets.RELATIVE_CI_KEY_PROJECT_B }}
          token: ${{ secrets.GITHUB_TOKEN }}

Example for `workflow_run` event

.github/workflow/build.yml

# ....
      # Upload "Project A" webpack-stats.json to use on relative-ci.yaml workflow
      - name: Project A - Upload webpack stats artifact
        uses: relative-ci/agent-upload-artifact-action@v2
        with:
          artifactName: project-a-relative-ci-artifacts
          webpackStatsFile: ./project-a/webpack-stats.json

      # Upload "Project B" webpack-stats.json to use on relative-ci.yaml workflow
      - name: Project B - Upload webpack stats artifact
        uses: relative-ci/agent-upload-artifact-action@v2
        with:
          artifactName: project-b-relative-ci-artifacts
          webpackStatsFile: ./project-b/webpack-stats.json

.github/workflows/relative-ci.yaml

# ...
    steps:
      - name: Project A - Send bundle stats and build information to RelativeCI
        uses: relative-ci/agent-action@v3.0.0-beta
        with:
          artifactName: project-a-relative-ci-artifacts
          key: ${{ secrets.RELATIVE_CI_KEY_PROJECT_A }}
          token: ${{ secrets.GITHUB_TOKEN }}

      - name: Project B - Send bundle stats and build information to RelativeCI
        uses: relative-ci/agent-action@v3.0.0-beta
        with:
          artifactName: project-b-relative-ci-artifacts
          key: ${{ secrets.RELATIVE_CI_KEY_PROJECT_B }}
          token: ${{ secrets.GITHUB_TOKEN }}

HelpHow to debug @relative-ci/agent GitHub action

Setup done

View your RelativeCI projects

Configure your project:

GitHub Commit Status review GitHub Check Report GitHub Pull Request Comment Slack Notification Invite team members

Guides:

Webpack config for better monitoring npm duplicate dependencies Analyze and compare bundle changes locally

Need help?Contact us via email, Twitter, or GitHub!

RelativeCI

In-depth bundle analysis and monitoring

Step 1. Output bundle stats JSON file

Step 2. Configure GitHub action

`push` / `pull_request`

`workflow_run`

`push` event

`pull_request` event

Build information

Extract commit message from git history

Extract commit message using GitHub API

`workflow_run` event

About workflows triggered by forked repositories or insecure workflows (dependabot updates)

Workflow 1: Build and upload bundle stats artifacts

Workflow 2. Send bundle stats and build information to RelativeCI

Secrets

`RELATIVE_CI_KEY` - required

`RELATIVE_CI_ENDPOINT` - required for RelativeCI Enterprise Cloud/Server

Inputs

Monorepo

Example for `push` / `pull_request` events

Example for `workflow_run` event

Setup done

Configure your project:

Guides:

Identify and fix bundle regressions before shipping to production

Bundle analyzer

Bundle monitoring

Bundle comparison

Step 1. Output bundle stats JSON file

Step 2. Configure GitHub action

push / pull_request

workflow_run

push event

pull_request event

Build information

Extract commit message from git history

Extract commit message using GitHub API

workflow_run event

About workflows triggered by forked repositories or insecure workflows (dependabot updates)

Workflow 1: Build and upload bundle stats artifacts

Workflow 2. Send bundle stats and build information to RelativeCI

Secrets

RELATIVE_CI_KEY - required

RELATIVE_CI_ENDPOINT - required for RelativeCI Enterprise Cloud/Server

Inputs

Monorepo

Example for push / pull_request events

Example for workflow_run event

Setup done

Configure your project:

Guides:

Identify and fix bundle regressions before shipping to production

Bundle analyzer

Bundle monitoring

Bundle comparison

`push` / `pull_request`

`workflow_run`

`push` event

`pull_request` event

`workflow_run` event

`RELATIVE_CI_KEY` - required

`RELATIVE_CI_ENDPOINT` - required for RelativeCI Enterprise Cloud/Server

Example for `push` / `pull_request` events

Example for `workflow_run` event