repo-fix/docs/advanced.md

5.2 KiB

Advanced usage

URL handling and Git layouts

repo-fix recognizes HTTP(S), SSH, Git protocol, and SCP-style URLs on dandaedre.com, git.dandaedre.com, and proxy.dandaedre.com. Legacy URLs such as git@dandaedre.com:Beffroi/reportist.git are corrected. Repository paths and .git suffixes are preserved, and the proxy's /gitea/ prefix is translated when switching between HTTPS and SSH.

Missing local URL entries are added from .gitmodules. Existing local URLs retain their own repository paths. Other hosts, relative URLs, and malformed values are skipped. Unrelated configuration, including active, is preserved.

The script supports ordinary .git directories, .git pointer files, and linked worktrees whose local configuration is shared. It recursively scans existing configuration under Git's modules directories, including nested or deinitialized submodules, and repairs their remote url, pushurl, and nested submodule URL entries. The selected repository's own remotes are not changed.

Nested working-tree .gitmodules files are not edited. Run the script inside each nested submodule when those declarations also need normalization.

Testing and coverage

The unit suite includes malformed-value cases and a small deterministic fuzz test for URL parsing. These checks are intended to catch crashes and unsafe path shapes, not to replace a dedicated fuzzer.

To run the same branch-coverage check as CI:

python3 -m venv .venv
.venv/bin/python -m pip install -r requirements-ci.txt
.venv/bin/coverage erase
.venv/bin/coverage run -m unittest discover -s tests -v
.venv/bin/coverage report

This exact command enforces the 80% line-coverage floor configured in pyproject.toml. The threshold is intentionally modest so it catches meaningful regressions without encouraging low-value tests. CI additionally writes coverage/coverage-summary.json temporarily to obtain the overall percentage for the coverage badge, then removes that summary.

The opt-in integration test shallow-clones Ravenous/ravenous_roll20.git through the HTTPS proxy and exercises dry-run safety, both URL formats, repeatability, recovery after git submodule sync, and correction of the legacy SSH hostname:

python3 -m unittest discover -s integration -v

The clone is removed after the test. It does not fetch submodules, execute code from Ravenous, test SSH connectivity, or recursively download submodules.

Jenkins CI

Configure Jenkins as a Pipeline from SCM or a multibranch pipeline with Jenkinsfile as the script path. The pipeline uses the rust_no_docker agent from Ravenous and requires Python 3.10 or newer, Git, and network access to PyPI, vulnerability data, and the Gitea HTTPS proxy. It creates isolated virtual environments; uv and Docker are not required.

The job must expose BRANCH_NAME (multibranch) or GIT_BRANCH (Pipeline from SCM). Cleanup fails safely when neither is available instead of risking mutable badge publication from an unidentified branch.

Before testing, CI runs two focused dependency gates:

  • pip-audit 2.10.1 fails on known vulnerabilities or dependency-collection errors.
  • pip-licenses 5.5.5 permits only MIT-licensed packages in the isolated application environment.

Coverage 7.16.1 and setuptools 80.9.0 are also pinned in requirements-ci.txt. Create the isolated application environment and run the gates locally with:

python3 -m venv .venv-app
.venv-app/bin/python -m pip install setuptools==80.9.0
.venv-app/bin/python -m pip install --no-build-isolation --no-deps .
.venv/bin/pip-audit --strict .
.venv/bin/pip-licenses --python=.venv-app/bin/python

The audit needs network access for resolution and current advisory data. The license allow-list should only change after reviewing a new dependency. The project currently has no runtime dependencies.

These gates do not analyze the standard library, Git, malicious packages, provenance, or undisclosed vulnerabilities. No broader hardening tools are in scope.

The network integration test runs by default. Disable the RUN_CLONE_TEST build parameter for an offline unit-test-only run. If the HTTPS clone requires authentication, configure Git credentials on the agent; interactive prompts are disabled and clone failures fail the build.

The authoritative project version is fix_submodules.__version__, exposed as the dynamic project version in pyproject.toml. During cleanup, including after a failed build, Jenkins generates and archives exactly these fingerprinted artifacts:

  • coverage/version.svg
  • coverage/test.svg
  • coverage/coverage.svg

Only a default-branch (main) build publishes those three files to /mnt/assets/coverage/Chado/repo-fix/main/. They are served at:

  • https://assets.dandaedre.com/coverage/Chado/repo-fix/main/version.svg
  • https://assets.dandaedre.com/coverage/Chado/repo-fix/main/test.svg
  • https://assets.dandaedre.com/coverage/Chado/repo-fix/main/coverage.svg

Configure the public server to mount the assets read-only, disable directory listing, serve SVG with a restrictive content security policy, and revalidate these mutable URLs or give them a short cache lifetime. Jenkins publication and public serving are deployment concerns; the pipeline does not push commits or send external checks.