From 036e6d2138f388e34099fbf2dc133cb45bfb267c Mon Sep 17 00:00:00 2001 From: Justin Kulikauskas <44813129+JustinKuli@users.noreply.github.com> Date: Sun, 30 Jun 2024 01:37:03 +0000 Subject: [PATCH] Publish coverage and docs to GH Pages Previously, the coverage reports were pushed to the wiki, but since the wiki is not meant for serving arbitrary HTML, viewing them properly required going through `raw.githack.com`. Also, the main `pkg.go.dev` site does not handle this repository well, possibly because it is a fork (also complicated by the archiving of the original) or because downloads of the package are very rare. Based on a suggestion in github (dot) com/golang/go/issues/2381, an updated GH action now downloads the contents of a local documentation server with `wget`, and modifies some local links with `sed` to get something which can be statically served. This mostly works, the main downside is that JS files seem to be missing. This adds on to the existing test step in the action, because that step is necessary for the coverage information. If additional resources are to be served on the GH Pages site, it might be a good idea to move to a separate workflow, even though it would require re-running the tests. Signed-off-by: Justin Kulikauskas <44813129+JustinKuli@users.noreply.github.com> --- .github/workflows/checks.yaml | 75 ++++++++++++++++++++++++++++++++++- README.md | 4 +- 2 files changed, 75 insertions(+), 4 deletions(-) diff --git a/.github/workflows/checks.yaml b/.github/workflows/checks.yaml index 0c3cd97..9eb2e8a 100644 --- a/.github/workflows/checks.yaml +++ b/.github/workflows/checks.yaml @@ -6,6 +6,12 @@ defaults: run: shell: bash +# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages +permissions: + contents: read + pages: write + id-token: write + jobs: cleanliness: name: Run Cleanliness Checks @@ -52,6 +58,13 @@ jobs: tests: name: Run Tests runs-on: ubuntu-latest + + # Prevent race conditions from multiple runs updating the wiki or GH pages. + # Additional runs will be queued as needed. + concurrency: + group: tests + cancel-in-progress: false + steps: - uses: actions/checkout@v4 @@ -63,6 +76,7 @@ jobs: make test grep -v 'zz_generated.deepcopy.go' raw-cover.out > cover.out + # This publishes a report and a badge in the wiki, which is useful for pull-requests. - name: Update coverage report uses: ncruces/go-coverage-report@v0 with: @@ -71,5 +85,62 @@ jobs: report: true chart: false amend: false - if: ${{ github.event_name == 'push' }} - continue-on-error: true + continue-on-error: false + + # The final steps publish the report, badge, and the (newly-generated) docs to GitHub Pages. + # They will only run when the branch is 'main' + - name: GH Pages - Setup + if: ${{ github.ref_name == 'main' }} + uses: actions/configure-pages@v5 + + - name: GH Pages - Generate + if: ${{ github.ref_name == 'main' }} + run: | + go install golang.org/x/pkgsite/cmd/pkgsite@latest + echo "Starting the doc server..." + pkgsite 2>/dev/null & + DOC_PID=$! + sleep 15 # Let it initialize + + echo "Downloading the generated doc site" + wget -r -q -np -N -E -p -k 'http://localhost:8080/open-cluster-management.io/governance-policy-nucleus@v0.0.0' + kill -9 $DOC_PID + + echo "Bringing all the files into a gh-pages directory" + mv 'localhost:8080' 'gh-pages' + + # Adjust some localhost links + find ./gh-pages -type f -name "*.html" -print0 | \ + xargs -0 sed -i 's|localhost:8080/files/workspaces|broken-source-link|g' + find ./gh-pages -type f -name "*.html" -print0 | \ + xargs -0 sed -i 's|http://localhost:8080|https://pkg.go.dev|g' + + # Copy these from the wiki (generated by ncruces/go-coverage-report) + cp ./.github/wiki/main/coverage.html gh-pages/coverage.html + cp ./.github/wiki/main/coverage.svg gh-pages/coverage.svg + + # Add a simple redirect index.html + cat << EOF > gh-pages/index.html + + + + Landing Page + + + + +

Redirecting to the docs page...

+ + + EOF + + - name: GH Pages - Upload + if: ${{ github.ref_name == 'main' }} + uses: actions/upload-pages-artifact@v3 + with: + path: './gh-pages' + + - name: GH Pages - Deploy + if: ${{ github.ref_name == 'main' }} + id: deployment + uses: actions/deploy-pages@v4 diff --git a/README.md b/README.md index 4827cae..407271b 100644 --- a/README.md +++ b/README.md @@ -1,8 +1,8 @@ [comment]: # " Copyright Contributors to the Open Cluster Management project " [![License](https://img.shields.io/:license-apache-blue.svg)](http://www.apache.org/licenses/LICENSE-2.0.html) [![Go Report Card](https://goreportcard.com/badge/github.com/JustinKuli/governance-policy-nucleus)](https://goreportcard.com/report/github.com/JustinKuli/governance-policy-nucleus) -[![Go Reference](https://pkg.go.dev/badge/image)](https://pkg.go.dev/github.com/JustinKuli/governance-policy-nucleus) -[![Go Coverage](https://github.com/JustinKuli/governance-policy-nucleus/wiki/main/coverage.svg)](https://raw.githack.com/wiki/JustinKuli/governance-policy-nucleus/main/coverage.html) +[![Go Reference](https://pkg.go.dev/badge/image)](https://justinkuli.github.io/governance-policy-nucleus/open-cluster-management.io/governance-policy-nucleus) +[![Go Coverage](https://justinkuli.github.io/governance-policy-nucleus/coverage.svg)](https://justinkuli.github.io/governance-policy-nucleus/coverage.html) # Governance Policy Nucleus