repo-fix/docs/advanced.md

123 lines
5.2 KiB
Markdown

# 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:
```bash
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:
```bash
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:
```bash
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.