123 lines
5.2 KiB
Markdown
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.
|