Develocity auto-injection for GitHub Actions

^{(self-hosted runners)}

This sample project demonstrates how to configure self-hosted GitHub Actions runners to automatically publish Build Scans® to Develocity from CI workflows of any project. The example demonstrates an approach for Gradle builds, but could be adapted for Maven or other build tools supported by Develocity.

Overview

In this example, the standard variable ACTIONS_RUNNER_HOOK_JOB_STARTED=<path-to>/job-started.sh is exported in the shell from which ./run.sh is running. It can also be placed in a .env file.

export ACTIONS_RUNNER_HOOK_JOB_STARTED=<path-to>/job-started.sh
./run.sh
#
# √ Connected to GitHub
#
# Current runner version: '2.328.0'
# Listening for jobs...

When a job is started on a self-hosted runner, GitHub Actions looks for an ACTIONS_RUNNER_HOOK_JOB_STARTED variable containing the path to an executable shell script. It executes that script.

The script then sets environment variables for all job steps.

# job-started.sh
echo "Enabling Develocity auto-injection for projects that use setup-gradle" >&2
cat >> "$GITHUB_ENV" << EOF
DEVELOCITY_INJECTION_ENABLED=true
DEVELOCITY_INJECTION_URL=https://ge.solutions-team.gradle.com
DEVELOCITY_INJECTION_DEVELOCITY_PLUGIN_VERSION=4.2.1
DEVELOCITY_INJECTION_CCUD_PLUGIN_VERSION=2.4.0
EOF

The setup-gradle action places Gradle initialization scripts on the environment. These scripts will inject the Develocity plugins into any build executed on this runner, unless these variables are overridden at the job level (job:env). In this example, the sample-gradle-project was enabled to automatically publishing Build Scans® for CI builds with no changes required to the project source.

References

• GitHub Actions self-hosted runners
• pre- and post-job scripts
• setup-gradle action Develocity integration

Usage

Prerequisites

• A Gradle project in a GitHub repository
• GitHub self-hosted runners

Setup in an existing runner

1. Copy the runner-hooks/ directory from this repository to the runner
2. Export the following variable where run.sh is ran or place it in a .env file next to run.sh:

ACTIONS_RUNNER_HOOK_JOB_STARTED=<path-to-runner-hooks>/job-started.sh

⚠️ For jobs running in a container (job:container), this is not applicable as-is. See Other approaches and caveats.

Trial setup with your own machine as a runner

1. Fork this repository
2. Access the repository Settings > Actions > Runners
3. Click "Add new self-hosted runner"
4. Select your OS and CPU architecture
5. Run the page's steps but create the following .env file next to run.sh

ACTIONS_RUNNER_HOOK_JOB_STARTED=<path-to-this-repository>/runner-hooks/job-started.sh

6. Run run.sh to listen for jobs
7. On GitHub, start the example workflow, which declares uses: self-hosted

Other approaches and caveats

• Auto-inject Develocity into builds that run in containers from self-hosted runners (Running jobs in a container): this example is partially applicable. The same environment variables should be used, which a setup-gradle step would pick up. Either use container customization scripts to define the same environment variables directly (without a hook script), or copy the hook script to images at image build time, or mount where the hook script is located.
• Auto-inject Develocity into builds that do not use the setup-gradle action: place the Gradle initialization script from develocity-ci-injection in addition to setting the environment variables. The init script will inject the integration on any build, if the variables are set. The setup-gradle action uses this init script internally.