Skip to content

Commit 5828cd4

Browse files
CodeYogiCoCodeYogiCo
committed
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).
1 parent 5dc1fa9 commit 5828cd4

2 files changed

Lines changed: 142 additions & 16 deletions

File tree

‎README.md‎

Lines changed: 105 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -21,7 +21,7 @@ Currently, this plugin supports two coverage file format.
2121
* jacoco for jvm based languages like java,kotlin,scala
2222
* cobertura can be used for golang projects using [gocov-xml](https://github.com/AlekSi/gocov-xml) utility
2323

24-
This plugin works out of box for [Vela](https://github.com/go-vela),a CI/CD open-sourced by target
24+
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.
2525

2626
## VELA Usage
2727

@@ -94,6 +94,110 @@ Once you have coverage.xml same can be passed as an input to plugin shown below
9494
|gh_api_key| false | | api key to auth for posting coverage comments<br><br>if not set, coverage details will not be commented on PR |
9595
|module | false | \<empty string\> | sub-module to use if operating inside a multi-module project (e.g. gradle multi-project build) |
9696
97+
## GitHub Actions Usage
98+
99+
On GitHub Actions you generate the coverage report in a step, then run the plugin
100+
image with the PR diff piped to its stdin. Posting the comment uses the built-in
101+
`GITHUB_TOKEN`, so the job needs `pull-requests: write`.
102+
103+
Leave the base URL unset for public github.com (it defaults to
104+
`https://api.github.com`). For GitHub Enterprise set `PARAMETER_GH_API_BASE_URL`
105+
to your API root, e.g. `https://git.example.com/api/v3`.
106+
107+
### Go (cobertura)
108+
109+
[gocover-cobertura](https://github.com/boumenot/gocover-cobertura) converts a Go
110+
coverage profile to cobertura in a single step (run via `go run`, nothing to install).
111+
112+
```yaml
113+
name: pr-code-coverage
114+
on:
115+
pull_request:
116+
117+
permissions:
118+
contents: read
119+
pull-requests: write
120+
121+
jobs:
122+
coverage:
123+
runs-on: ubuntu-latest
124+
# GITHUB_TOKEN is read-only on fork PRs, so restrict to same-repo PRs.
125+
if: github.event.pull_request.head.repo.full_name == github.repository
126+
steps:
127+
- uses: actions/checkout@v4
128+
with:
129+
fetch-depth: 0 # need the base branch present to diff against
130+
131+
- uses: actions/setup-go@v5
132+
with:
133+
go-version: '1.26'
134+
135+
- name: Generate coverage profile
136+
run: go test -coverpkg=./... -coverprofile=coverage.txt ./...
137+
138+
- name: Convert to cobertura
139+
run: go run github.com/boumenot/gocover-cobertura@latest < coverage.txt > coverage.xml
140+
141+
- name: Report coverage on changed lines
142+
env:
143+
PARAMETER_COVERAGE_TYPE: cobertura
144+
PARAMETER_COVERAGE_FILE: coverage.xml
145+
# Must equal the absolute path in the cobertura <source> element,
146+
# which gocover-cobertura sets to the dir `go test` ran in.
147+
PARAMETER_SOURCE_DIRS: ${{ github.workspace }}
148+
PARAMETER_GH_API_KEY: ${{ secrets.GITHUB_TOKEN }}
149+
BUILD_PULL_REQUEST_NUMBER: ${{ github.event.pull_request.number }}
150+
REPOSITORY_ORG: ${{ github.repository_owner }}
151+
REPOSITORY_NAME: ${{ github.event.repository.name }}
152+
run: |
153+
git fetch --no-tags origin "${{ github.base_ref }}"
154+
git --no-pager diff --unified=0 "origin/${{ github.base_ref }}" -- '*.go' \
155+
| docker run --rm -i \
156+
-e PARAMETER_COVERAGE_TYPE -e PARAMETER_COVERAGE_FILE \
157+
-e PARAMETER_SOURCE_DIRS -e PARAMETER_GH_API_KEY \
158+
-e BUILD_PULL_REQUEST_NUMBER -e REPOSITORY_ORG -e REPOSITORY_NAME \
159+
-v "${{ github.workspace }}:${{ github.workspace }}" \
160+
-w "${{ github.workspace }}" \
161+
--entrypoint /plugin \
162+
pullrequestcc/pull-request-code-coverage:latest
163+
```
164+
165+
For JVM projects, generate a jacoco report instead and set
166+
`PARAMETER_COVERAGE_TYPE=jacoco`, `PARAMETER_COVERAGE_FILE` to the jacoco XML, and
167+
`PARAMETER_SOURCE_DIRS` to your source dir(s) (e.g. `src/main/java`).
168+
169+
### Environment variables
170+
171+
Outside Vela, configure the plugin with these environment variables (Vela's
172+
`parameters:` map to the same `PARAMETER_*` names automatically):
173+
174+
| variable | required | description |
175+
|---|---|---|
176+
| `PARAMETER_COVERAGE_TYPE` | yes | `jacoco` or `cobertura` |
177+
| `PARAMETER_COVERAGE_FILE` | yes | path to the coverage report |
178+
| `PARAMETER_SOURCE_DIRS` | yes | comma-separated source dirs (see the cobertura `<source>` note above) |
179+
| `PARAMETER_MODULE` | no | sub-module path in a multi-module project |
180+
| `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 |
181+
| `PARAMETER_GH_API_BASE_URL` | no | GitHub API root; defaults to `https://api.github.com`. For Enterprise use `https://HOST/api/v3` |
182+
| `PARAMETER_DEBUG` | no | `true` for verbose path-matching logs |
183+
| `BUILD_PULL_REQUEST_NUMBER` | no\* | PR number to comment on |
184+
| `REPOSITORY_ORG` | no\* | repository owner |
185+
| `REPOSITORY_NAME` | no\* | repository name |
186+
187+
\* required together for the PR comment; if any is missing the plugin only prints to the console.
188+
189+
### Using the container entrypoint directly
190+
191+
The image's default entrypoint (`scripts/start.sh`) can compute the diff for you
192+
in any CI or a plain `docker run`. Point it at the target branch and it fetches,
193+
diffs, and pipes the result to the plugin:
194+
195+
| variable | description |
196+
|---|---|
197+
| `PARAMETER_TARGET_BRANCH` | branch to diff against (Vela uses `VELA_PULL_REQUEST_TARGET` as a fallback) |
198+
| `PARAMETER_RUN_DIR` | directory containing the `plugin` binary (default: image root) |
199+
| `GIT_NETRC_MACHINE` / `GIT_NETRC_USERNAME` / `GIT_NETRC_PASSWORD` | optional `~/.netrc` git auth for private remotes (Vela uses `VELA_NETRC_*`) |
200+
97201
# Development
98202

99203
This project needs go (>= 1.26.3) to be installed. Make sure you run

‎scripts/start.sh‎

Lines changed: 37 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -2,29 +2,51 @@
22

33
set -Eeuo pipefail
44

5-
6-
7-
if [[ ! -f ~/.netrc ]]
8-
then
9-
echo "~/.netrc does not exist, creating..."
5+
# pull-request-code-coverage entrypoint.
6+
#
7+
# Computes the unified diff between the PR head and its target branch and pipes
8+
# it to the plugin, which reports coverage for the changed lines. This script is
9+
# CI-agnostic (Vela, GitHub Actions, plain Docker): set the generic variables
10+
# below. Vela variables are honoured as fallbacks so existing Vela pipelines
11+
# keep working unchanged.
12+
13+
# --- optional git auth via ~/.netrc -----------------------------------------
14+
# Needed only when the target branch lives on a remote that git must authenticate
15+
# to fetch. Provide GIT_NETRC_* (generic) or VELA_NETRC_* (Vela). Skipped when
16+
# unset, or when a ~/.netrc already exists (e.g. mounted/created by the CI).
17+
netrc_machine="${GIT_NETRC_MACHINE:-${VELA_NETRC_MACHINE:-}}"
18+
netrc_login="${GIT_NETRC_USERNAME:-${VELA_NETRC_USERNAME:-}}"
19+
netrc_password="${GIT_NETRC_PASSWORD:-${VELA_NETRC_PASSWORD:-}}"
20+
21+
if [[ ! -f ~/.netrc && -n "$netrc_machine" ]]; then
22+
echo "~/.netrc does not exist, creating from netrc environment variables..."
1023

1124
cat >~/.netrc <<EOF
12-
machine $VELA_NETRC_MACHINE
13-
login $VELA_NETRC_USERNAME
14-
password $VELA_NETRC_PASSWORD
25+
machine $netrc_machine
26+
login $netrc_login
27+
password $netrc_password
1528
EOF
1629
fi
1730

18-
31+
# Enable command tracing only after the secret-bearing block above, so the
32+
# netrc password is never echoed to the logs.
1933
set -x
2034

2135
module="${PARAMETER_MODULE:-}"
22-
PARAMETER_RUN_DIR="${PARAMETER_RUN_DIR:-}"
23-
branch="${VELA_PULL_REQUEST_TARGET:-}"
36+
run_dir="${PARAMETER_RUN_DIR:-}"
2437

25-
git config --global user.name "vela"
26-
git config --global user.email "vela@xyz.com"
38+
# Branch to diff the PR against: generic variable first, Vela fallback.
39+
branch="${PARAMETER_TARGET_BRANCH:-${VELA_PULL_REQUEST_TARGET:-}}"
40+
if [[ -z "$branch" ]]; then
41+
echo "No target branch set: provide PARAMETER_TARGET_BRANCH (or VELA_PULL_REQUEST_TARGET)." >&2
42+
exit 1
43+
fi
2744

45+
# Avoid git "dubious ownership" failures when the checkout is owned by a
46+
# different user inside the container (common on GitHub Actions and other CI).
47+
git config --global --add safe.directory "*" || true
48+
git config --global user.name "${GIT_AUTHOR_NAME:-pull-request-code-coverage}"
49+
git config --global user.email "${GIT_AUTHOR_EMAIL:-pull-request-code-coverage@users.noreply.github.com}"
2850

29-
git fetch --no-tags origin "$branch"
30-
git --no-pager diff --unified=0 origin/"$branch" $module | $PARAMETER_RUN_DIR/plugin
51+
git fetch --no-tags origin "$branch"
52+
git --no-pager diff --unified=0 "origin/$branch" $module | "$run_dir/plugin"

0 commit comments

Comments
 (0)