This page contains the setup guide for the RelativeCI agent v5. Go to RelativeCI agent v4 to follow the setup guide for the previous 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).
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 with: webpackStatsFile: ./webpack-stats.json key: ${{ secrets.RELATIVE_CI_KEY }}
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).
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 with: webpackStatsFile: ./webpack-stats.json key: ${{ secrets.RELATIVE_CI_KEY }}
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:
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 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, pass GITHUB_TOKEN
secret to the agent. When the token is present, the agent will fetch the corresponding commit from GitHub.
contents: read
permission is required to fetch the commit details from the GitHub API. Read more
about GITHUB_TOKEN
permissions
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
env:
# Send bundle stats and build information to RelativeCI - name: Send bundle stats to RelativeCI uses: relative-ci/agent-action@v3 with: webpackStatsFile: ./webpack-stats.json key: ${{ secrets.RELATIVE_CI_KEY }} token: ${{ secrets.GITHUB_TOKEN }}
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.
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.
actions: read
permission is required to download the artifact uploaded during the previous
workflow. Read more
about GITHUB_TOKEN
permissions
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 with: key: ${{ secrets.RELATIVE_CI_KEY }} token: ${{ secrets.GITHUB_TOKEN }}
Secrets
Inputs
key
(required): RelativeCI API project keytoken
(required onworkflow_run
events): GitHub API token - used to fetch the bundle stats artifact.webpackStatsFile
(required onpush
/pull_request
events): Path to webpack stats fileartifactName
(defaultrelative-ci-artifacts
onworkflow_run
): The name of the artifact uploaded during the build workflow that contains the bundle statsendpoint
(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 informationdebug
(defaultfalse
): 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
# ... # Project A - Send bundle stats and build information to RelativeCI - name: Project A - Send bundle stats to RelativeCI uses: relative-ci/agent-action@v3 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 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@v3 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 with: artifactName: project-b-relative-ci-artifacts key: ${{ secrets.RELATIVE_CI_KEY_PROJECT_B }} token: ${{ secrets.GITHUB_TOKEN }}