Skip to content

Maintainer setup

Steps that need a browser or account-level access, so automation cannot do them. Commands assume the GitHub CLI authenticated as the repository owner.

SonarQube Cloud (formerly SonarCloud)

The sonarcloud workflow skips the analysis with a visible notice until this is done.

  1. Sign in to SonarQube Cloud with GitHub.
  2. Create the organization bound to the GitHub account SebasBarrera (free plan for public repositories) and import harness-engineering. The expected keys are the ones in sonar-project.properties: organization sebasbarrera, project key SebasBarrera_harness-engineering. If SonarQube Cloud assigns different keys, update that file.
  3. In the project, Administration → Analysis Method: turn off Automatic Analysis. It is incompatible with analysis from CI.
  4. Create a token (My Account → Security) and store it as a repository secret:
gh secret set SONAR_TOKEN --repo SebasBarrera/harness-engineering
  1. Re-run the workflow (gh workflow run sonarcloud.yml --ref develop), check the first analysis, and then add the quality-gate badge to the README.

GitHub token used by automation

Automation uses the GitHub CLI authenticated as the repository owner. Every work branch reaches develop through a pull request (see CONTRIBUTING.md), so a fine-grained token restricted to this repository needs Pull requests: Read and write besides Administration, Contents, Workflows, Issues, Actions, Pages and Secrets (read and write) and Attestations, Code scanning alerts and Commit statuses (read).

Dependabot pull requests

Dependabot opens pull requests against develop. Review and merge them in the web UI (or with gh pr merge --merge) once their checks are green. Python version bumps of the Docker base image should be evaluated deliberately: the image is pinned by digest to python:3.12-slim.

GitHub Pages

Pages is configured with Source: GitHub Actions and is deployed by pages.yml on pushes to main. The gh-pages branch is only a data branch for the benchmark trend written by benchmarks.yml; it is not the Pages source.

Branch rulesets

protect-main and protect-develop block deletion and non-fast-forward pushes. Work branches are merged through pull requests once every blocking check is green. With a second maintainer, add the pull_request rule (one approval, CODEOWNERS review) and make the checks listed in monitoring required.

Private vulnerability reporting, secret scanning and Dependabot

Already enabled on the repository: private vulnerability reporting, secret scanning with push protection, Dependabot alerts and security updates. Review them under Security.

PyPI

GitHub Packages has no Python registry, so releases go to GitHub Releases (wheel, sdist, SBOM, SHA256SUMS, attestation) and GHCR (image), and, once you enable it, to PyPI.

release.yml already contains the publish-pypi job: it needs the release job, runs only on v* tags, uses the pypi environment, holds only id-token: write, and uploads the same distributions the release job built and attested (kept as the python-distributions workflow artifact) with pypa/gh-action-pypi-publish pinned to the full commit SHA of v1.14.2. It runs only when the repository variable PYPI_PUBLISH is true; without it the job is skipped and the release is created as before. What only you can do:

  1. Create or sign in to your account on pypi.org with two-factor authentication, and check that the name governed-agent-harness is free (it could not be checked from the automation environment).
  2. Under Your account → Publishing, add a pending publisher: project governed-agent-harness, owner SebasBarrera, repository harness-engineering, workflow release.yml, environment pypi.
  3. In GitHub Settings → Environments, create the pypi environment (it is also created on first use). Adding yourself as a required reviewer gives a manual approval before each upload, which is worth having because PyPI never accepts the same version twice.
  4. Turn publication on:
gh variable set PYPI_PUBLISH --body true --repo SebasBarrera/harness-engineering
  1. Push the next v* tag. The first upload creates the project from the pending publisher. Turn it off with gh variable delete PYPI_PUBLISH.

The Spanish guide es/publicacion.md walks through the release flow and these steps.

Local workspace of the maintainer

The thesis manuscript (Documento/), the authoring prompt, the extracted cut and .local/ live next to the repository on the maintainer's machine and are ignored by .gitignore. They must never be committed; CI enforces this with the privacy denylist.