This page contains the setup guide for the current stable version of the agent(v4). Go to agent v5 beta to follow the setup guide for the new beta 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, you can use the following scenarious to configure relative-ci/agent-action:
push / pull_request
One-step setup for private or small projects
workflow_run
Two steps workflow recommended for open-source projects, projects that use forks, or teams with increased security requirements
push/pull_request event
Add relative-ci/agent-action after your build step(the build step will output the bundle stats depending on Step 1. setup).
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@v2 with: webpackStatsFile: ./webpack-stats.json key: ${{ secrets.RELATIVE_CI_KEY }} token: ${{ secrets.GITHUB_TOKEN }}pull_request event
When the action runs during the pull_request event, GitHub reports the merge commit information:
GITHUB_REF='refs/pull/2377/merge'GITHUB_SHA='Merge #abc124 into #abc123'relative-ci/agent-action collects the build information from the event data (event.json) and sends the id & message corresponding to the actual commit that triggered the pull request.
workflow_run event
About workflows triggered by forked repositories and 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 GHES yet. If you are on GHES, you must use relative-ci/agent-upload-artifact-action@v1.
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.jsonWorkflow 2. Send bundle stats and build information to RelativeCI
Create a new workflow triggered by the previous build workflow (Build) to download the bundle stat
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.
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@v2 with: key: ${{ secrets.RELATIVE_CI_KEY }} token: ${{ secrets.GITHUB_TOKEN }}Secrets
Inputs
key(required): RelativeCI project keytoken(required): GitHub tokenwebpackStatsFile(required onpush/pull_requestevents): Path to webpack stats fileendpoint(required for Enterprise Cloud customers)slug(defaultGITHUB_REPOSITORY): Your project slugincludeCommitMessage( defaulttrue): Get current commit message (git log -1 --pretty=%B) and send it to RelativeCI as part of the build informatindebug(defaultfalse): Enable debug outputartifactName(defaultrelative-ci-artifactsonworkflow_run): The name of the artifact with bundle stats uploaded by another workflow
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
# ... # Project A - Send bundle stats and build information to RelativeCI - name: Project A - Send bundle stats to RelativeCI uses: relative-ci/agent-action@v2 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@v2 with: webpackStatsFile: ./project-b/webpack-stats.json key: ${{ secrets.RELATIVE_CI_KEY_PROJECT_B }} token: ${{ secrets.GITHUB_TOKEN }}Example for workflow_run event
# .... # 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# ... steps: - name: Project A - Send bundle stats and build information to RelativeCI uses: relative-ci/agent-action@v2 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@v2 with: artifactName: project-a-relative-ci-artifacts key: ${{ secrets.RELATIVE_CI_KEY_PROJECT_B }} token: ${{ secrets.GITHUB_TOKEN }}