From 5828cd4f71f80dd7defdc2d55d6c3728799af640 Mon Sep 17 00:00:00 2001 From: Vishal Vaibhav Date: Thu, 21 May 2026 15:44:51 +0530 Subject: [PATCH] docs: add GitHub Actions usage; make start.sh CI-agnostic Document a GitHub Actions workflow and the plugin's environment variables, and rework scripts/start.sh to run under any CI (generic vars with Vela fallbacks). --- README.md | 106 ++++++++++++++++++++++++++++++++++++++++++++++- scripts/start.sh | 52 ++++++++++++++++------- 2 files changed, 142 insertions(+), 16 deletions(-) diff --git a/README.md b/README.md index 75e11cd..41891ef 100644 --- a/README.md +++ b/README.md @@ -21,7 +21,7 @@ Currently, this plugin supports two coverage file format. * jacoco for jvm based languages like java,kotlin,scala * cobertura can be used for golang projects using [gocov-xml](https://github.com/AlekSi/gocov-xml) utility -This plugin works out of box for [Vela](https://github.com/go-vela),a CI/CD open-sourced by target +This plugin works out of the box with [Vela](https://github.com/go-vela) (a CI/CD platform open-sourced by Target), [GitHub Actions](#github-actions-usage), and any CI that can run a container. ## VELA Usage @@ -94,6 +94,110 @@ Once you have coverage.xml same can be passed as an input to plugin shown below |gh_api_key| false | | api key to auth for posting coverage comments

if not set, coverage details will not be commented on PR | |module | false | \ | sub-module to use if operating inside a multi-module project (e.g. gradle multi-project build) | +## GitHub Actions Usage + +On GitHub Actions you generate the coverage report in a step, then run the plugin +image with the PR diff piped to its stdin. Posting the comment uses the built-in +`GITHUB_TOKEN`, so the job needs `pull-requests: write`. + +Leave the base URL unset for public github.com (it defaults to +`https://api.github.com`). For GitHub Enterprise set `PARAMETER_GH_API_BASE_URL` +to your API root, e.g. `https://git.example.com/api/v3`. + +### Go (cobertura) + +[gocover-cobertura](https://github.com/boumenot/gocover-cobertura) converts a Go +coverage profile to cobertura in a single step (run via `go run`, nothing to install). + +```yaml +name: pr-code-coverage +on: + pull_request: + +permissions: + contents: read + pull-requests: write + +jobs: + coverage: + runs-on: ubuntu-latest + # GITHUB_TOKEN is read-only on fork PRs, so restrict to same-repo PRs. + if: github.event.pull_request.head.repo.full_name == github.repository + steps: + - uses: actions/checkout@v4 + with: + fetch-depth: 0 # need the base branch present to diff against + + - uses: actions/setup-go@v5 + with: + go-version: '1.26' + + - name: Generate coverage profile + run: go test -coverpkg=./... -coverprofile=coverage.txt ./... + + - name: Convert to cobertura + run: go run github.com/boumenot/gocover-cobertura@latest < coverage.txt > coverage.xml + + - name: Report coverage on changed lines + env: + PARAMETER_COVERAGE_TYPE: cobertura + PARAMETER_COVERAGE_FILE: coverage.xml + # Must equal the absolute path in the cobertura element, + # which gocover-cobertura sets to the dir `go test` ran in. + PARAMETER_SOURCE_DIRS: ${{ github.workspace }} + PARAMETER_GH_API_KEY: ${{ secrets.GITHUB_TOKEN }} + BUILD_PULL_REQUEST_NUMBER: ${{ github.event.pull_request.number }} + REPOSITORY_ORG: ${{ github.repository_owner }} + REPOSITORY_NAME: ${{ github.event.repository.name }} + run: | + git fetch --no-tags origin "${{ github.base_ref }}" + git --no-pager diff --unified=0 "origin/${{ github.base_ref }}" -- '*.go' \ + | docker run --rm -i \ + -e PARAMETER_COVERAGE_TYPE -e PARAMETER_COVERAGE_FILE \ + -e PARAMETER_SOURCE_DIRS -e PARAMETER_GH_API_KEY \ + -e BUILD_PULL_REQUEST_NUMBER -e REPOSITORY_ORG -e REPOSITORY_NAME \ + -v "${{ github.workspace }}:${{ github.workspace }}" \ + -w "${{ github.workspace }}" \ + --entrypoint /plugin \ + pullrequestcc/pull-request-code-coverage:latest +``` + +For JVM projects, generate a jacoco report instead and set +`PARAMETER_COVERAGE_TYPE=jacoco`, `PARAMETER_COVERAGE_FILE` to the jacoco XML, and +`PARAMETER_SOURCE_DIRS` to your source dir(s) (e.g. `src/main/java`). + +### Environment variables + +Outside Vela, configure the plugin with these environment variables (Vela's +`parameters:` map to the same `PARAMETER_*` names automatically): + +| variable | required | description | +|---|---|---| +| `PARAMETER_COVERAGE_TYPE` | yes | `jacoco` or `cobertura` | +| `PARAMETER_COVERAGE_FILE` | yes | path to the coverage report | +| `PARAMETER_SOURCE_DIRS` | yes | comma-separated source dirs (see the cobertura `` note above) | +| `PARAMETER_MODULE` | no | sub-module path in a multi-module project | +| `PARAMETER_GH_API_KEY` | no | token used to post the PR comment (`GITHUB_TOKEN` on Actions); `PLUGIN_GH_API_KEY` is also accepted. If unset, results only print to the console | +| `PARAMETER_GH_API_BASE_URL` | no | GitHub API root; defaults to `https://api.github.com`. For Enterprise use `https://HOST/api/v3` | +| `PARAMETER_DEBUG` | no | `true` for verbose path-matching logs | +| `BUILD_PULL_REQUEST_NUMBER` | no\* | PR number to comment on | +| `REPOSITORY_ORG` | no\* | repository owner | +| `REPOSITORY_NAME` | no\* | repository name | + +\* required together for the PR comment; if any is missing the plugin only prints to the console. + +### Using the container entrypoint directly + +The image's default entrypoint (`scripts/start.sh`) can compute the diff for you +in any CI or a plain `docker run`. Point it at the target branch and it fetches, +diffs, and pipes the result to the plugin: + +| variable | description | +|---|---| +| `PARAMETER_TARGET_BRANCH` | branch to diff against (Vela uses `VELA_PULL_REQUEST_TARGET` as a fallback) | +| `PARAMETER_RUN_DIR` | directory containing the `plugin` binary (default: image root) | +| `GIT_NETRC_MACHINE` / `GIT_NETRC_USERNAME` / `GIT_NETRC_PASSWORD` | optional `~/.netrc` git auth for private remotes (Vela uses `VELA_NETRC_*`) | + # Development This project needs go (>= 1.26.3) to be installed. Make sure you run diff --git a/scripts/start.sh b/scripts/start.sh index d87678a..b7443be 100755 --- a/scripts/start.sh +++ b/scripts/start.sh @@ -2,29 +2,51 @@ set -Eeuo pipefail - - -if [[ ! -f ~/.netrc ]] -then - echo "~/.netrc does not exist, creating..." +# pull-request-code-coverage entrypoint. +# +# Computes the unified diff between the PR head and its target branch and pipes +# it to the plugin, which reports coverage for the changed lines. This script is +# CI-agnostic (Vela, GitHub Actions, plain Docker): set the generic variables +# below. Vela variables are honoured as fallbacks so existing Vela pipelines +# keep working unchanged. + +# --- optional git auth via ~/.netrc ----------------------------------------- +# Needed only when the target branch lives on a remote that git must authenticate +# to fetch. Provide GIT_NETRC_* (generic) or VELA_NETRC_* (Vela). Skipped when +# unset, or when a ~/.netrc already exists (e.g. mounted/created by the CI). +netrc_machine="${GIT_NETRC_MACHINE:-${VELA_NETRC_MACHINE:-}}" +netrc_login="${GIT_NETRC_USERNAME:-${VELA_NETRC_USERNAME:-}}" +netrc_password="${GIT_NETRC_PASSWORD:-${VELA_NETRC_PASSWORD:-}}" + +if [[ ! -f ~/.netrc && -n "$netrc_machine" ]]; then + echo "~/.netrc does not exist, creating from netrc environment variables..." cat >~/.netrc <&2 + exit 1 +fi +# Avoid git "dubious ownership" failures when the checkout is owned by a +# different user inside the container (common on GitHub Actions and other CI). +git config --global --add safe.directory "*" || true +git config --global user.name "${GIT_AUTHOR_NAME:-pull-request-code-coverage}" +git config --global user.email "${GIT_AUTHOR_EMAIL:-pull-request-code-coverage@users.noreply.github.com}" -git fetch --no-tags origin "$branch" -git --no-pager diff --unified=0 origin/"$branch" $module | $PARAMETER_RUN_DIR/plugin +git fetch --no-tags origin "$branch" +git --no-pager diff --unified=0 "origin/$branch" $module | "$run_dir/plugin"