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.
- Sign in to SonarQube Cloud with GitHub.
- Create the organization bound to the GitHub account
SebasBarrera(free plan for public repositories) and importharness-engineering. The expected keys are the ones insonar-project.properties: organizationsebasbarrera, project keySebasBarrera_harness-engineering. If SonarQube Cloud assigns different keys, update that file. - In the project, Administration → Analysis Method: turn off Automatic Analysis. It is incompatible with analysis from CI.
- Create a token (My Account → Security) and store it as a repository secret:
gh secret set SONAR_TOKEN --repo SebasBarrera/harness-engineering
- 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:
- Create or sign in to your account on pypi.org with two-factor
authentication, and check that the name
governed-agent-harnessis free (it could not be checked from the automation environment). - Under Your account → Publishing, add a pending publisher: project
governed-agent-harness, ownerSebasBarrera, repositoryharness-engineering, workflowrelease.yml, environmentpypi. - In GitHub Settings → Environments, create the
pypienvironment (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. - Turn publication on:
gh variable set PYPI_PUBLISH --body true --repo SebasBarrera/harness-engineering
- Push the next
v*tag. The first upload creates the project from the pending publisher. Turn it off withgh 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.