Skip to content

github-integration.md

Latest commit

 

History

History
249 lines (187 loc) · 9.28 KB

github-integration.md

File metadata and controls

249 lines (187 loc) · 9.28 KB
Raw

GitHub badge + report

Publish a continuously updated Kibi requirement-health report on GitHub Pages, with a clickable % proven badge in the repository README.

Badge and report are one feature. Someone who sees 87% proven needs to open the report to see what that percentage represents and which requirements are missing proof. Kibi does not host badges or reports; GitHub Pages is the expected publisher. Knowledge stays in the repository's .kb/ directory.

The root README is the discoverable entry point. This document covers the same integration in more detail.

What the badge means

A badge such as kibi | 87% proven is the share of applicable current Kibi requirements that have current proof. Non-current (for example superseded) requirements are excluded, as are requirements marked not applicable to proof.

The published HTML report is the place to inspect:

  • which requirements are proven
  • which are missing proof
  • contradictions
  • stale verification state
  • other requirement-health details already exposed by kibi report

The badge and index.html always come from one kibi report coverage snapshot. Do not compute a separate GitHub-only percentage.

Recommended flow: badge + full report

1. Enable GitHub Pages

In GitHub:

Settings → Pages → Source → GitHub Actions

This is the only expected GitHub UI step. Kibi does not change repository settings for you.

2. Add the Kibi workflow

Copy the canonical workflow to:

.github/workflows/kibi-report.yml

The file to copy is docs/examples/github/kibi-report.yml. It is byte-identical to the template shipped in kibi-cli.

One build-report job generates the report. Pull requests validate that generation and upload the candidate site as an ordinary workflow artifact. Only the repository default branch (it does not assume the branch is named main) and workflow_dispatch may deploy GitHub Pages. A pull_request event never deploys Pages, never replaces the canonical report or badge, and never receives pages: write or id-token: write. The workflow uses pull_request, not pull_request_target, with repository-level contents: read. GitHub Actions checkouts are detached, so the workflow sets KIBI_BRANCH to the pull-request head ref or the pushed/dispatched branch name before kibi sync and kibi report.

The generate job:

  1. checks out the candidate GitHub Actions ref (the PR merge commit on pull requests, otherwise the pushed or dispatched commit)
  2. sets up Node.js
  3. installs SWI-Prolog
  4. installs project dependencies with npm
  5. runs kibi sync
  6. runs kibi report --output kibi-report (the job fails if this fails)
  7. on pull_request, uploads the kibi-report/ directory as the kibi-pr-report artifact (HTML report plus badge)
  8. on the default branch or workflow_dispatch, copies that output under pages/kibi-report/ so the public path is /kibi-report/ and uploads it as a GitHub Pages artifact

The deploy-report job then deploys that Pages artifact. It does not run for pull requests. Pushes to non-default branches start the workflow and skip both jobs. The workflow does not build or test the rest of the application, does not commit generated files, and does not use an orphan gh-pages branch.

3. Add the clickable badge

[![Kibi requirement health](https://OWNER.github.io/REPOSITORY/kibi-report/badge.svg)](https://OWNER.github.io/REPOSITORY/kibi-report/)

Replace OWNER and REPOSITORY with the lowercase GitHub Pages owner and repository path. Clicking the badge must open the report. Files are published under /kibi-report/ so Kibi does not occupy the Pages site root.

This workflow still replaces the GitHub Pages deployment. If the repository already publishes a site, copy kibi-report/ into that site's output instead of using this workflow as the only deploy.

Expected URLs

Repository Report Badge
OWNER/REPOSITORY https://OWNER.github.io/REPOSITORY/kibi-report/ https://OWNER.github.io/REPOSITORY/kibi-report/badge.svg
OWNER/OWNER.github.io (owner site) https://OWNER.github.io/kibi-report/ https://OWNER.github.io/kibi-report/badge.svg

The image URL must be anonymously reachable for GitHub to render it in a public README. For a private report, publish both files to an authenticated static host that your intended audience can access. GitHub Actions artifacts expire and are not a stable badge URL.

Do not commit generated kibi-report/ files.

CLI shortcut

kibi init --github performs normal kibi init behavior, then scaffolds the same documented integration:

kibi init --github

It:

  • writes .github/workflows/kibi-report.yml from the packaged template
  • adds the clickable badge to an existing root README when a github.com remote can be determined
  • adds kibi-report/ to .gitignore when missing
  • prints the Pages enable instruction

It is safe to run more than once. Matching workflows are left as already configured. Customized workflows are not overwritten. An existing Kibi badge is not duplicated. If no README exists, the workflow is still written and the badge Markdown is printed. If owner/repository cannot be determined from a github.com remote, the workflow is still written and placeholder badge Markdown is printed instead of inventing a URL.

Package-manager adaptations

The canonical workflow uses npm because that matches the documented Kibi install (npm install --save-dev kibi-cli ... and npm exec -- kibi).

Change only the Node setup cache and the install/exec commands:

pnpm

- uses: actions/setup-node@v5
  with:
    node-version: 24
    cache: pnpm
- run: pnpm install --frozen-lockfile
- run: pnpm exec kibi sync
- run: pnpm exec kibi report --output kibi-report

Install the pnpm action (pnpm/action-setup) before setup-node if the runner does not already have pnpm.

Yarn

- uses: actions/setup-node@v5
  with:
    node-version: 24
    cache: yarn
- run: yarn install --frozen-lockfile
- run: yarn kibi sync
- run: yarn kibi report --output kibi-report

Bun

- uses: oven-sh/setup-bun@v2
- run: bun install --frozen-lockfile
- run: bunx kibi sync
- run: bunx kibi report --output kibi-report

Keep kibi-cli as a project dependency so CI uses the version the repository pinned. Do not add application build or test steps just to generate the report.

Badge-only opt-out

Prefer the full report. To publish only the badge:

kibi init --github --badge-only

Or copy docs/examples/github/kibi-badge.yml to .github/workflows/kibi-badge.yml.

That workflow still runs kibi report (same snapshot, same % proven). Pull requests upload the generated report directory as kibi-pr-report and still do not deploy Pages. Default-branch and workflow_dispatch publishes only badge.svg under /kibi-report/. The README link should point at this section rather than pretending a report exists:

[![Kibi requirement health](https://OWNER.github.io/REPOSITORY/kibi-report/badge.svg)](https://github.com/Looted/kibi/blob/develop/docs/github-integration.md#what-the-badge-means)

--badge-only without --github is rejected. --github by itself always means badge + full report.

Troubleshooting

The workflow succeeds but https://OWNER.github.io/REPOSITORY/kibi-report/ is 404. Enable Settings → Pages → Source → GitHub Actions. Until that is set, Pages deployments do not go live. The report is not at the Pages site root.

The badge image is a broken picture in the README. The SVG URL must be anonymously reachable. Private Pages sites will not render in public READMEs. Confirm /kibi-report/badge.svg loads in a logged-out browser.

The workflow is skipped on every feature-branch push. Report generation runs on pull_request, workflow_dispatch, or a push to the repository default branch. Pushes to other branches start the workflow and then skip the jobs. Open a pull request to validate a candidate report, change the GitHub default branch, or use Run workflow for a one-off publish. GitHub Pages still deploys only from the default branch or workflow_dispatch.

kibi: command not found or npm exec -- kibi fails. Install kibi-cli as a project dependency and commit the lockfile. The workflow does not install Kibi globally.

swipl: command not found. The workflow installs swi-prolog with apt-get on ubuntu-latest. Kibi requires SWI-Prolog 9.0+. If the runner image is older, install from the SWI-Prolog PPA instead.

Pages published the wrong site / two Kibi workflows. A repository can host one Pages site. Keep either kibi-report.yml or kibi-badge.yml, not both.

kibi init --github did not overwrite my workflow. If .github/workflows/kibi-report.yml already exists and differs from the template, Kibi leaves it in place. Compare it with docs/examples/github/kibi-report.yml.

Owner/repository could not be determined. kibi init --github only parses github.com remotes (HTTPS or SSH). GitHub Enterprise hosts are not auto-filled. The workflow is still written; paste the printed badge Markdown after replacing OWNER/REPOSITORY.