add-ideas/govoplan
1
0
Fork 0
Code Issues 3 Pull Requests Actions Packages Projects Releases Wiki Activity

Initialize GovOPlaN meta repository

Browse Source
This commit is contained in:
Albrecht Degering
2026-07-11 17:16:58 +02:00
commit 70109afc78
70 changed files with 11641 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

321
docs/GITEA_ISSUES.md Normal file
View File

@@ -0,0 +1,321 @@
# Gitea Issues And Wiki Workflow
Gitea issues are the canonical backlog for GovOPlaN work: bugs, feature requests, tasks, tech debt, TODO migrations, open decisions, and blocked work should live there. Gitea wiki pages are the canonical project reference for durable project context mirrored from repository docs and product-directory notes.
The same pattern is reusable outside GovOPlaN for any project where Codex works in a local checkout, VSCodium or another editor is used for human inspection, and Gitea is the issue tracker. In that setup, Gitea is the durable coordination layer; Codex and the editor are clients of that state.
## Initial Setup
The repository contains Gitea issue templates in `.gitea/ISSUE_TEMPLATE`, a pull request template in `.gitea/PULL_REQUEST_TEMPLATE.md`, and the label taxonomy in `docs/gitea-labels.json`.
The scripts infer this repository from `origin` (`git@git.add-ideas.de:add-ideas/govoplan.git`). Override inference when needed:
```bash
export GITEA_URL=https://git.add-ideas.de
export GITEA_OWNER=add-ideas
export GITEA_REPO=govoplan
export GITEA_TOKEN=...
```
The API scripts also read `GITEA_*` values from the target repository's `.env` file. That file is gitignored in this repo, so it is suitable for local tokens:
```bash
GITEA_TOKEN=...
# Optional if origin inference is not enough:
GITEA_URL=https://git.add-ideas.de
GITEA_OWNER=add-ideas
GITEA_REPO=govoplan
```
For a shared credentials file outside the target repository, pass `--env-file`:
```bash
./tools/gitea/gitea-sync-labels.py --env-file /path/to/private/gitea.env --apply
```
Create a Gitea token with issue read/write access and label-management
permission for the repository. On scoped-token instances, this usually means
issue read/write and, if label writes are rejected, repository write permission
too.
For GovOPlaN repositories, prefer organization labels for the shared taxonomy.
Creating or updating organization labels requires a token with
`write:organization`. Repository label management only needs repository label
permission, but it duplicates the taxonomy into each repository.
Preview and apply labels:
```bash
cd /mnt/DATA/git/govoplan
./tools/gitea/gitea-sync-labels.py
./tools/gitea/gitea-sync-labels.py --apply
```
Preview and apply the shared taxonomy as organization labels:
```bash
cd /mnt/DATA/git/govoplan
./tools/gitea/gitea-sync-labels.py --scope organization --env-file /home/zemion/.config/gitea/gitea.env
./tools/gitea/gitea-sync-labels.py --scope organization --env-file /home/zemion/.config/gitea/gitea.env --apply
```
The import helpers resolve repository labels and organization labels. Repository
labels win when a repository defines the same name locally, but a repository does
not need a local copy of every shared `type/*`, `status/*`, `priority/*`,
`module/*`, `area/*`, `source/*`, or `codex/*` label.
After the `.gitea` files are pushed to the default branch, Gitea will show the issue template chooser. Blank issues are disabled by `.gitea/ISSUE_TEMPLATE/config.yaml`.
## Multiple Repositories And Workspaces
The helper scripts are path-based and can run from the meta checkout against any repository with a Gitea remote:
```bash
cd /mnt/DATA/git/govoplan
./tools/gitea/gitea-sync-labels.py --root /mnt/DATA/git/govoplan-mail --apply
./tools/gitea/gitea-todo-import.py --root /mnt/DATA/git/govoplan-mail
./tools/gitea/gitea-codex-note.py --root /mnt/DATA/git/govoplan-mail --issue 123 --status progress
```
Each target repository is inferred from its own `origin` remote. Use `GITEA_URL`, `GITEA_OWNER`, or `GITEA_REPO` only when a workspace has unusual remotes or the Gitea web URL cannot be inferred from SSH.
When the meta checkout drives another workspace, prefer `--env-file` for shared
credentials instead of putting `GITEA_REPO` in the meta `.env`; a repo-specific
`GITEA_REPO` can accidentally override target inference.
For non-GovOPlaN projects, provide a project-specific label file and module/project label:
```bash
./tools/gitea/gitea-sync-labels.py \
--root /path/to/project \
--labels-file /path/to/project/docs/gitea-labels.json \
--apply
./tools/gitea/gitea-todo-import.py \
--root /path/to/project \
--module-label project/example \
--extra-label area/backend
```
If another project does not use `area/*` labels, disable area inference:
```bash
./tools/gitea/gitea-todo-import.py \
--root /path/to/project \
--module-label project/example \
--no-area-labels
```
Install or refresh the shared issue templates in sibling or external repositories:
```bash
./tools/gitea/gitea-install-workflow.py /mnt/DATA/git/govoplan-mail
./tools/gitea/gitea-install-workflow.py /mnt/DATA/git/govoplan-mail --apply
```
The installer rewrites the default template label from `module/core` to the module label inferred from the target repository name. Known mappings cover the packaged GovOPlaN repositories, and any other `govoplan-<name>` checkout maps to `module/<name>`. For another workspace or repository name, pass an explicit label:
```bash
./tools/gitea/gitea-install-workflow.py /path/to/repo --module-label module/example --apply
```
Use `--include-labels-file` if a repository should carry its own copy of `docs/gitea-labels.json`; otherwise keep the shared taxonomy in the meta repo and run the sync script from the meta repo.
For a fully portable workflow kit, copy these files into the other project:
- `tools/gitea/gitea_common.py`
- `tools/gitea/gitea-sync-labels.py`
- `tools/gitea/gitea-todo-import.py`
- `tools/gitea/gitea-codex-note.py`
- `tools/gitea/gitea-install-workflow.py`
- `.gitea/ISSUE_TEMPLATE/*`
- `.gitea/PULL_REQUEST_TEMPLATE.md`
- a project-specific `docs/gitea-labels.json`
Keep credentials out of the repository. Put `GITEA_TOKEN` in the shell environment, a gitignored `.env`, a local direnv file, or the user-level Codex/VSCodium environment setup.
## Label Taxonomy
Use one `type/*` label:
- `type/bug`
- `type/feature`
- `type/task`
- `type/debt`
- `type/docs`
Use one `status/*` label while the issue is open:
- `status/triage`: needs ownership, priority, or acceptance criteria.
- `status/ready`: ready to implement.
- `status/in-progress`: actively being worked.
- `status/blocked`: blocked on an external dependency, credential, or decision.
- `status/needs-info`: blocked on clarification.
Use one `priority/*` label when prioritization matters: `priority/p0`, `priority/p1`, `priority/p2`, or `priority/p3`.
Use `module/*` and `area/*` labels to route work. Module labels are not exclusive because cross-module work can exist. Core issues should still preserve ownership boundaries: module-specific implementation belongs in the owning module repository.
Use `codex/ready` when the issue has enough context for Codex to work from, and `codex/needs-human` when a human decision is required first.
## Moving TODOs Into Gitea
Preview inline markers:
```bash
cd /mnt/DATA/git/govoplan
./tools/gitea/gitea-todo-import.py
```
Create missing issues after labels are synced:
```bash
./tools/gitea/gitea-todo-import.py --apply
```
The importer scans `TODO`, `FIXME`, `XXX`, and `HACK` markers, skips markers that already reference an issue, applies `source/todo-scan`, and writes a hidden fingerprint into each generated issue body so reruns do not duplicate already imported items.
When touching code with an imported marker, either remove the marker as part of the fix or replace it with a short reference:
```python
# TODO(gitea#123): keep only if the local pointer is still useful
```
Do not add new untracked TODO comments. Create the Gitea issue first, then reference it inline only when the local pointer materially helps future readers.
For a broader project import across all local repositories hosted on `git.add-ideas.de`, use the generic backlog importer:
```bash
./tools/gitea/gitea-import-all-backlogs.py --env-file /home/zemion/.config/gitea/gitea.env
./tools/gitea/gitea-import-all-backlogs.py --env-file /home/zemion/.config/gitea/gitea.env --apply
```
It scans repository and product-directory files with backlog-like names, resolves
shared labels from the organization label catalogue where available, creates only
missing fallback repository labels when needed, imports missing open work, and
deduplicates reruns by hidden fingerprint and normalized title.
## Mirroring Project Docs Into Gitea Wikis
Preview wiki pages for all local repositories hosted on `git.add-ideas.de`, cross-referenced with product directories under `/mnt/DATA/Nextcloud/ADD ideas UG/Products`:
```bash
cd /mnt/DATA/git/govoplan
./tools/gitea/gitea-sync-wiki.py --env-file /home/zemion/.config/gitea/gitea.env
```
Apply the wiki mirror:
```bash
./tools/gitea/gitea-sync-wiki.py --env-file /home/zemion/.config/gitea/gitea.env --apply
```
After renaming or deleting repository docs, prune previously managed wiki pages
that no longer have a source file:
```bash
./tools/gitea/gitea-sync-wiki.py --env-file /home/zemion/.config/gitea/gitea.env --repo govoplan-core --prune-managed --apply
```
The default apply path uses the Gitea wiki git repository, not one REST API
request per page. It keeps a local checkout cache below
`/tmp/codex-gitea-wiki-sync`, commits changed pages once per repository, and
pushes that commit. This is much faster and avoids REST wiki-page timeouts.
Use `--transport api` only when the wiki git remote is unavailable.
Limit a sync to one repository or one generated page while working:
```bash
./tools/gitea/gitea-sync-wiki.py --repo govoplan-core --apply
./tools/gitea/gitea-sync-wiki.py --repo govoplan-core --page Repo-docs-MODULE-ARCHITECTURE --apply
```
Page-limited syncs do not rewrite `Codex-Project-Index`; run a full repository
sync when the set of mirrored pages changes.
The wiki sync mirrors durable text documents only: root README-style files, docs/codex project docs, and selected product notes such as roadmap, plan, concept, pitch, and whitepaper files. It skips generated folders, dependency/build output, `.gitea` templates, and filenames that look credential-related.
Each managed wiki page contains a `codex-wiki-sync` marker and a source path. Reruns update only managed pages unless `--overwrite-unmanaged` is passed. Each repository also gets a managed `Codex-Project-Index` page linking the mirrored pages.
Use the wiki for durable context:
- project overviews and architecture
- workflows, operating notes, and setup references
- product concepts, plans, pitches, and whitepapers
- historical context that helps interpret issues
Keep active state in issues:
- open tasks, TODOs, feature requests, and bugs
- priority, blocking status, and acceptance criteria
- Codex progress updates and implementation notes
## Codex State Updates
Codex should read the relevant issue before making changes when issue access is available. During or after work, Codex should add issue comments with the state that would otherwise drift into local notes:
- scope understood
- files changed
- tests or manual checks run
- blockers or decisions needed
- follow-up issues created
Preview and post a standardized note:
```bash
./tools/gitea/gitea-codex-note.py \
--issue 123 \
--status progress \
--summary "Implemented capability metadata fallback." \
--changed src/govoplan_core/modules/registry.py \
--test "./.venv/bin/python -m unittest tests.test_module_system"
./tools/gitea/gitea-codex-note.py \
--issue 123 \
--status progress \
--summary "Implemented capability metadata fallback." \
--changed src/govoplan_core/modules/registry.py \
--test "./.venv/bin/python -m unittest tests.test_module_system" \
--apply
```
Use `--close --apply` only when the acceptance criteria are satisfied and verification is recorded.
## Ownership Rules
Create the issue in the repository that owns the change:
- `govoplan-core`: platform runner, DB/session primitives, auth, tenancy, RBAC, governance, module discovery, migrations, shared WebUI shell, and generic WebUI components.
- `govoplan-access`: access, identity, authentication, sessions, API keys, RBAC, groups, users, and access administration.
- `govoplan-mail`: mail-specific backend, frontend, message workflows, and mail integrations.
- `govoplan-files`: files-specific backend, frontend, storage, and file workflows.
- `govoplan-campaign`: campaign-specific backend, frontend, policy, and template behavior.
For cross-cutting work, create a tracking issue in `govoplan-core` and link module issues from it. Do not use the core issue as a dumping ground for module-specific implementation details.
## Cleaning Up Mirrored Sources
After backlog files have been imported into issues and durable context has been mirrored to wiki, old duplicate sources can be removed from git only when they are tracked files and the Gitea issue/wiki state has been verified. Prefer deleting backlog, TODO, roadmap, and one-off planning files that have become duplicate state.
Do not delete standard repository entry points such as `README`, `LICENSE`, `SECURITY`, or package metadata just because they are mirrored to the wiki. They remain useful for repository browsing, package registries, and developer onboarding.
Do not delete untracked files or files outside git history as part of automated cleanup unless there is a separate backup or explicit human confirmation for that specific path.
## Docs Versus Issues
Keep durable facts in docs:
- architecture and extension points
- command references
- module boundaries
- operational conventions
Keep changing state in Gitea:
- TODOs and follow-ups
- bugs and feature requests
- blocked status
- acceptance criteria
- implementation notes from active work
If a decision becomes durable architecture, write the durable result into docs and link back to the issue for history.

180
docs/META_REPOSITORY_MIGRATION_AUDIT.md Normal file
View File

@@ -0,0 +1,180 @@
# Meta Repository Migration Audit
This audit records which existing GovOPlaN files should move toward the
`govoplan` meta repository and which should remain with their current runtime
owner.
## Website Repository Rename
The former `govoplan-web` repository has been renamed to
`addideas-govoplan-website`. It is a public website and catalog publication
target, not an installable GovOPlaN runtime module.
Resolved target name:
- `addideas-govoplan-website`
The rename happened server-side in Gitea first. Local checkout paths, remotes,
docs, and release/catalog defaults should use the new name.
The renamed repository should remain categorized as `website`, not `module`.
## Move To `govoplan`
These are whole-product/operator concerns and should be owned by the meta
repository.
### Release Orchestration
Former location:
- core-local release and catalog helper scripts
Target shape:
- command entry points live in `govoplan/tools`
- repository lists come from `govoplan/repositories.json`
- generated catalogs are written to the renamed public site repository
- core keeps only runtime catalog validation/signing primitives used by the
installer
### Cross-Repository Gitea Workflow Tooling
Former location:
- core-local Gitea helper scripts
- source issue templates copied into each repo under `.gitea/`
- the shared label taxonomy JSON file
Target shape:
- source templates and label taxonomy live in `govoplan`
- sync/import/migration helpers live in `govoplan/tools`
- generated/copy-installed `.gitea/` files may remain in each repository
because Gitea reads them repository-locally
- repo-specific AGENTS or issue guidance can remain repo-local when it contains
module-specific instructions
### Whole-Product CI
Former location:
- core-local whole-product workflow definitions
Target shape:
- whole-product workflows live in `govoplan/.gitea/workflows`
- workflows bootstrap or use sibling checkouts based on `repositories.json`
- core keeps core-only workflows if needed later
Notes:
- Gitea workflows are repository-local, so moving them changes which repository
triggers the job.
- The workflow scripts must stop assuming the checked-out repository is
`govoplan-core`.
### Security Audit Toolbox
Former location:
- core-local security audit toolbox files
- core-local audit dependency and Gitleaks configuration files
Reason to move:
- the tool already supports `--scope govoplan`
- the `govoplan` scan mounts the parent directory and scans sibling repos
- this is an operator/security workspace function, not runtime core behavior
Target shape:
- `govoplan/tools/checks/security-audit/`
- `govoplan/tools/checks/check-security-audit.sh`
- `govoplan/requirements-audit.txt`
- `govoplan/.gitleaks.toml`
### Whole-Product Docker
Former locations:
- core-local shared development Docker profiles
- website-local public-site Compose profile
Target shape:
- shared development and production-like composition move under `govoplan/dev`
- deploy/public-site composition can live under `govoplan/docker`
- module-specific testbeds stay module-local:
- `govoplan-campaign/dev/mail-testbed/docker-compose.yml`
- `govoplan-files/dev/connectors/docker-compose.yml`
## Keep In Core
These are runtime/kernel concerns and should stay in `govoplan-core`.
- installer/runtime code under `govoplan_core.core.module_installer`
- module discovery, registry, route aggregation, and lifecycle contracts
- catalog validation primitives used by the runtime installer
- configuration package validation and safety contracts
- database/session primitives and migration orchestration APIs
- core WebUI shell and module contribution contracts
Canonical operator entry points should be in `govoplan`.
## Keep In Public Site Repository
After the rename, the website repository should keep:
- Vite/React public website source
- screenshots/content source notes
- static catalog assets under `public/catalogs/...`
- website-specific catalog asset validator if it validates static publication
contents
- website Dockerfile and simple site-serving compose, unless a whole-product
deployment compose takes over in `govoplan`
It should not own:
- release version bumping
- cross-repository tagging
- catalog generation/signing keys
- installer logic
- module orchestration
## Rename Follow-Up References
Known references reviewed after the server-side rename:
- `govoplan/repositories.json`
- `govoplan/docs/REPOSITORY_STRUCTURE.md`
- `govoplan/docker/README.md`
- `govoplan-core/docs/RELEASE_DEPENDENCIES.md`
- `govoplan-core/docs/MODULE_ARCHITECTURE.md`
- moved release helper references
- moved Gitea helper references
- public site `README.md`, `package.json`, `package-lock.json`,
`docker-compose.yml`, and catalog key rotation runbook
## Suggested Migration Order
1. Update local checkout path, remote, repository manifest, and docs.
2. Move Gitea helper scripts and source templates from core to meta.
3. Move release/catalog command entry points from core to meta and convert
repository discovery to `repositories.json`.
4. Move whole-product Gitea Actions workflows to meta.
5. Move security audit toolbox to meta.
6. Move/wrap whole-product Docker composition in meta.
7. Remove core compatibility wrappers once docs and workflows use `govoplan`.
## Current State
Completed in the meta repository:
- canonical tools live in `govoplan/tools`
- release/catalog/Gitea/security-audit tools have been moved from core to meta
- whole-product Gitea workflows have been moved to `govoplan/.gitea/workflows`
- shared PostgreSQL and production-like Docker profiles live under `govoplan/dev`
- core-local wrappers for moved commands have been removed
- the meta `scripts` compatibility layer has been removed; use `govoplan/tools`

133
docs/REPOSITORY_STRUCTURE.md Normal file
View File

@@ -0,0 +1,133 @@
# GovOPlaN Repository Structure
GovOPlaN uses separate repositories for runtime modules, connector modules,
system orchestration, and public website/catalog publication.
## Categories
### system
System repositories are not optional runtime modules. They provide platform
execution, orchestration, development entry points, installer tooling, or core
runtime contracts.
Current system repositories:
- `govoplan`: meta repository for whole-product orchestration.
- `govoplan-core`: runtime kernel/server runner, module registry, shared UI
shell, installer, migration orchestration, and core contracts.
### module
Runtime modules provide user-visible product behavior. They can include backend
routes, database migrations, frontend contributions, permissions, docs, workers,
and lifecycle hooks.
Modules must communicate through core contracts, capabilities, providers, and
routes. They must not import another module's internal implementation directly.
### connector
Connector repositories adapt GovOPlaN capabilities to external protocols,
platforms, and integration formats. A connector may be a runtime module, but its
business responsibility is transport/integration, not product semantics.
Examples:
- `govoplan-rest`
- `govoplan-soap`
- `govoplan-fit-connect`
- `govoplan-xoev`
- `govoplan-xrechnung`
- `govoplan-xta-osci`
- `govoplan-connectors`
### website
Website repositories are public content or publication targets. They are not
installed into a GovOPlaN runtime.
Current website repository:
- `addideas-govoplan-website`: public website and release catalog publication target.
## Meta Repository Role
`govoplan` is the canonical operator entry point. Whole-product commands should
be available here first:
- development launch
- repository bootstrap/status
- whole-product Docker composition
- release tagging
- catalog publication
- installer/daemon orchestration
- cross-repository Gitea issue/wiki/label helpers
- security and dependency audit tooling
Whole-product command implementations live under `govoplan/tools`.
Core keeps runtime-specific commands only.
Repositories are linked through `repositories.json` and scripts rather than git
submodules. Development checkouts can keep their own branches and dirty state,
while release/catalog tooling can still resolve the exact repository list from
one place. If a deployment profile later needs pinned SHAs for every repository,
generate that lock as a release artifact instead of making day-to-day
development depend on submodule updates.
## Docker Placement
Whole-product Docker and production-like deployment composition belongs in
`govoplan`.
Current shared profiles:
- `dev/postgres`
- `dev/production-like`
Website-specific serving profiles stay with `addideas-govoplan-website`.
Module-specific test beds stay in the owning module repository. Examples:
- `govoplan-files/dev/connectors`
- `govoplan-campaign/dev/mail-testbed`
- connector protocol test beds in their connector repositories
This keeps local module tests close to the code while giving operators one
repository for product deployment.
## addideas-govoplan-website and Release Logic
`addideas-govoplan-website` should be treated as the public website and catalog publication
target, not as the release orchestrator.
The release workflow should be invoked from `govoplan`. It may write signed
catalog artifacts into `addideas-govoplan-website/public/catalogs/...` and then build or
deploy the website.
A separate `govoplan-release` repository should only be introduced if release
logic becomes an independently versioned service or toolchain. For now, a
separate repository would add coordination overhead without a clear boundary.
If embeddable public widgets become a runtime capability later, create a
separate installable module for that. The public website repository should stay
website/publication content only.
## Config Import/Export
Configuration import/export is runtime administration behavior. It should stay
with core/admin until it grows into a separately installable product capability.
Create a `govoplan-config` module only if configuration packages need their own
module lifecycle, permissions, migrations, background jobs, or public API.
## No govoplan-meta Runtime Module
Do not add a `govoplan-meta` runtime module for repository metadata. Repository
metadata belongs in this meta repository. Installed runtime metadata belongs in
the core module registry and module manifests.
If a runtime "system" surface is needed, it should be a core/admin/ops feature
backed by explicit capabilities, not a pseudo-module that mirrors repository
state.

143
docs/SECURITY_AUDIT.md Normal file
View File

@@ -0,0 +1,143 @@
# Security Audit Toolchain
GovOPlaN uses a free/open-source-first audit toolchain that can run locally,
inside a container, and in Gitea Actions.
## Tools
- Semgrep: multi-language SAST, with GovOPlaN-specific local rules plus
explicit public registry rulesets in CI/full runs.
- Bandit: Python AST security checks.
- Ruff `S` rules: fast flake8-bandit-compatible Python security linting.
- Gitleaks: committed-secret scanning.
- Trivy: filesystem dependency, secret, and misconfiguration scanning.
- pip-audit and npm audit: package vulnerability scanning from dependency
manifests/locks.
- OSV-Scanner: recursive dependency vulnerability scan in full mode.
- jscpd: duplicated-code reports in full mode.
- Radon/Xenon: Python complexity reports and thresholds in full mode.
## Local Usage
Build and run the toolbox from this repository:
```bash
cd /mnt/DATA/git/govoplan
tools/checks/security-audit/run.sh --mode ci --scope current
```
Scan all sibling GovOPlaN repositories under `/mnt/DATA/git`:
```bash
cd /mnt/DATA/git/govoplan
tools/checks/security-audit/run.sh --mode full --scope govoplan
```
Reports are written to `audit-reports/`, which is intentionally ignored by git.
The wrapper tags the toolbox image by a fingerprint of the Dockerfile and
`requirements-audit.txt`. If those inputs have not changed, subsequent runs reuse
the existing local image instead of reinstalling all tools. The stable alias is
`govoplan/security-audit:local` unless `SECURITY_AUDIT_IMAGE` is set.
Force a cached rebuild:
```bash
tools/checks/security-audit/run.sh --mode ci --scope current --rebuild
```
Refresh from upstream base images and package ranges:
```bash
tools/checks/security-audit/run.sh --mode ci --scope current --update
```
Build or refresh the toolbox without running an audit:
```bash
tools/checks/security-audit/run.sh --mode quick --scope current --build-only
tools/checks/security-audit/run.sh --mode quick --scope current --update --build-only
```
## Modes
- `quick`: local Semgrep rules, Bandit, Ruff security rules, Gitleaks.
- `ci`: quick plus Semgrep public registry rulesets, Trivy, pip-audit, npm audit.
- `full`: ci plus OSV-Scanner, jscpd, Radon, and Xenon.
## Gating
The initial Gitea workflow runs in report-only mode:
```bash
SECURITY_AUDIT_FAIL_ON_FINDINGS=0
```
This avoids blocking every push while the first baseline is reviewed. After the
baseline is clean, switch the workflow to:
```bash
SECURITY_AUDIT_FAIL_ON_FINDINGS=1
```
or run locally with:
```bash
tools/checks/security-audit/run.sh --mode ci --scope current --strict
```
## Audit Burndown Workflow
Treat Gitea issues as the active audit state. A full GovOPlaN audit should
produce one tracker issue in `add-ideas/govoplan` and child issues in the
repository that owns each fix.
Use the tracker issue for:
- report path, timestamp, mode, and scope
- scanner counts by category
- clean scanners and resolved findings
- links to child issues
- the next audit run target
Use child issues for concrete code or configuration changes. Apply
`source/security-audit` to every issue created from a report, then add the
most specific audit label:
- `audit/quick-fix`: narrow direct remediation
- `audit/structural`: behavior or architecture needs review
- `audit/complexity`: Radon/Xenon maintainability finding
- `audit/duplication`: jscpd duplication finding
- `audit/false-positive`: reviewed narrow false positive or accepted risk
- `audit/needs-design`: human decision needed before implementation
Keep active implementation status in issues instead of committing generated
audit reports. `audit-reports/` is ignored; quote the report directory and the
important scanner counts in the tracker issue.
## Image Freshness
The regular `Security Audit` workflow reuses the fingerprinted toolbox image
when the Docker daemon is persistent, which is the normal case for the
self-hosted Gitea runner using the host Docker socket. The separate
`Security Audit Toolbox Update` workflow runs weekly with
`SECURITY_AUDIT_UPDATE=1`; it pulls current base images and re-resolves the
allowed tool version ranges into a refreshed local image.
## Direct Host Usage
The container is the recommended path. For direct host usage, install the Python
tools first:
```bash
cd /mnt/DATA/git/govoplan
python -m venv .venv
./.venv/bin/python -m pip install -r requirements-audit.txt
```
Then install the non-Python tools (`gitleaks`, `trivy`, `osv-scanner`, `jscpd`)
through the host package manager or vendor instructions and run:
```bash
tools/checks/check-security-audit.sh --mode quick --scope current
```

458
docs/gitea-labels.json Normal file
View File

@@ -0,0 +1,458 @@
[
{
"name": "type/bug",
"color": "d73a4a",
"description": "A reproducible defect, regression, or incorrect behavior.",
"exclusive": true
},
{
"name": "type/feature",
"color": "0e8a16",
"description": "New user-visible behavior or platform capability.",
"exclusive": true
},
{
"name": "type/task",
"color": "1d76db",
"description": "Implementation, maintenance, migration, or operational work.",
"exclusive": true
},
{
"name": "type/debt",
"color": "fbca04",
"description": "Cleanup, refactoring, risk reduction, or deferred engineering work.",
"exclusive": true
},
{
"name": "type/docs",
"color": "5319e7",
"description": "Documentation, process, or developer workflow work.",
"exclusive": true
},
{
"name": "priority/p0",
"color": "b60205",
"description": "Immediate stop-the-line priority.",
"exclusive": true
},
{
"name": "priority/p1",
"color": "d93f0b",
"description": "High priority for the next focused work window.",
"exclusive": true
},
{
"name": "priority/p2",
"color": "fbca04",
"description": "Normal planned priority.",
"exclusive": true
},
{
"name": "priority/p3",
"color": "c2e0c6",
"description": "Low priority or opportunistic cleanup.",
"exclusive": true
},
{
"name": "status/triage",
"color": "d4c5f9",
"description": "Needs review, ownership, priority, or acceptance criteria.",
"exclusive": true
},
{
"name": "status/ready",
"color": "0e8a16",
"description": "Ready for implementation.",
"exclusive": true
},
{
"name": "status/in-progress",
"color": "0052cc",
"description": "Currently being worked.",
"exclusive": true
},
{
"name": "status/blocked",
"color": "b60205",
"description": "Cannot progress without a decision, dependency, credential, or external change.",
"exclusive": true
},
{
"name": "status/needs-info",
"color": "f9d0c4",
"description": "Needs clarifying input before implementation can proceed safely.",
"exclusive": true
},
{
"name": "module/access",
"color": "0e8a16",
"description": "GovOPlaN access, identity, authentication, RBAC, and administration behavior.",
"exclusive": false
},
{
"name": "module/addresses",
"color": "5319e7",
"description": "GovOPlaN Addresses module behavior or integration.",
"exclusive": false
},
{
"name": "module/admin",
"color": "006b75",
"description": "GovOPlaN Admin module behavior or integration.",
"exclusive": false
},
{
"name": "module/appointments",
"color": "d876e3",
"description": "GovOPlaN Appointments module behavior or integration.",
"exclusive": false
},
{
"name": "module/audit",
"color": "0e8a16",
"description": "GovOPlaN Audit module behavior or integration.",
"exclusive": false
},
{
"name": "module/calendar",
"color": "bfd4f2",
"description": "GovOPlaN Calendar module behavior or integration.",
"exclusive": false
},
{
"name": "module/campaign",
"color": "d876e3",
"description": "GovOPlaN campaign module behavior or integration.",
"exclusive": false
},
{
"name": "module/cases",
"color": "1d76db",
"description": "GovOPlaN Cases module behavior or integration.",
"exclusive": false
},
{
"name": "module/connectors",
"color": "c2e0c6",
"description": "GovOPlaN Connectors module behavior or integration.",
"exclusive": false
},
{
"name": "module/core",
"color": "0052cc",
"description": "GovOPlaN core runner, shared primitives, shell, or extension points.",
"exclusive": false
},
{
"name": "module/dms",
"color": "c5def5",
"description": "GovOPlaN Dms module behavior or integration.",
"exclusive": false
},
{
"name": "module/erp",
"color": "fef2c0",
"description": "GovOPlaN Erp module behavior or integration.",
"exclusive": false
},
{
"name": "module/files",
"color": "006b75",
"description": "GovOPlaN files module behavior or integration.",
"exclusive": false
},
{
"name": "module/fit-connect",
"color": "fbca04",
"description": "GovOPlaN Fit Connect module behavior or integration.",
"exclusive": false
},
{
"name": "module/forms",
"color": "f9d0c4",
"description": "GovOPlaN Forms module behavior or integration.",
"exclusive": false
},
{
"name": "module/identity-trust",
"color": "d4c5f9",
"description": "GovOPlaN Identity Trust module behavior or integration.",
"exclusive": false
},
{
"name": "module/identity",
"color": "bfd4f2",
"description": "GovOPlaN Identity module behavior or integration.",
"exclusive": false
},
{
"name": "module/idm",
"color": "0052cc",
"description": "GovOPlaN Idm module behavior or integration.",
"exclusive": false
},
{
"name": "module/ledger",
"color": "5319e7",
"description": "GovOPlaN Ledger module behavior or integration.",
"exclusive": false
},
{
"name": "module/mail",
"color": "5319e7",
"description": "GovOPlaN mail module behavior or integration.",
"exclusive": false
},
{
"name": "module/notifications",
"color": "d876e3",
"description": "GovOPlaN Notifications module behavior or integration.",
"exclusive": false
},
{
"name": "module/ops",
"color": "0e8a16",
"description": "GovOPlaN Ops module behavior or integration.",
"exclusive": false
},
{
"name": "module/organizations",
"color": "bfdadc",
"description": "GovOPlaN Organizations module behavior or integration.",
"exclusive": false
},
{
"name": "module/payments",
"color": "bfd4f2",
"description": "GovOPlaN Payments module behavior or integration.",
"exclusive": false
},
{
"name": "module/policy",
"color": "d93f0b",
"description": "GovOPlaN Policy module behavior or integration.",
"exclusive": false
},
{
"name": "module/portal",
"color": "1d76db",
"description": "GovOPlaN Portal module behavior or integration.",
"exclusive": false
},
{
"name": "module/postbox",
"color": "d93f0b",
"description": "GovOPlaN Postbox module behavior or integration.",
"exclusive": false
},
{
"name": "module/reporting",
"color": "c2e0c6",
"description": "GovOPlaN Reporting module behavior or integration.",
"exclusive": false
},
{
"name": "module/search",
"color": "bfdadc",
"description": "GovOPlaN Search module behavior or integration.",
"exclusive": false
},
{
"name": "module/scheduling",
"color": "d93f0b",
"description": "GovOPlaN Scheduling module behavior or integration.",
"exclusive": false
},
{
"name": "module/tasks",
"color": "c5def5",
"description": "GovOPlaN Tasks module behavior or integration.",
"exclusive": false
},
{
"name": "module/templates",
"color": "fef2c0",
"description": "GovOPlaN Templates module behavior or integration.",
"exclusive": false
},
{
"name": "module/tenancy",
"color": "e4e669",
"description": "GovOPlaN Tenancy module behavior or integration.",
"exclusive": false
},
{
"name": "module/workflow",
"color": "f9d0c4",
"description": "GovOPlaN Workflow module behavior or integration.",
"exclusive": false
},
{
"name": "module/xoev",
"color": "d4c5f9",
"description": "GovOPlaN Xoev module behavior or integration.",
"exclusive": false
},
{
"name": "module/xrechnung",
"color": "0052cc",
"description": "GovOPlaN Xrechnung module behavior or integration.",
"exclusive": false
},
{
"name": "module/xta-osci",
"color": "5319e7",
"description": "GovOPlaN Xta Osci module behavior or integration.",
"exclusive": false
},
{
"name": "area/auth",
"color": "bfd4f2",
"description": "Authentication, sessions, access bootstrap, or login behavior.",
"exclusive": false
},
{
"name": "area/tenancy",
"color": "bfdadc",
"description": "Tenant boundaries, provisioning, or tenant-scoped data behavior.",
"exclusive": false
},
{
"name": "area/rbac",
"color": "c5def5",
"description": "Permissions, roles, delegation, or authorization policy.",
"exclusive": false
},
{
"name": "area/governance",
"color": "fef2c0",
"description": "Governance policy, audit, privacy, retention, or compliance behavior.",
"exclusive": false
},
{
"name": "area/module-system",
"color": "bfe5bf",
"description": "Module discovery, manifests, capabilities, routing, or optional integrations.",
"exclusive": false
},
{
"name": "area/migrations",
"color": "e4e669",
"description": "Alembic migrations, schema bootstrap, or persistence evolution.",
"exclusive": false
},
{
"name": "area/webui",
"color": "1d76db",
"description": "Shared WebUI shell, frontend components, routing, or frontend tests.",
"exclusive": false
},
{
"name": "area/api",
"color": "5319e7",
"description": "HTTP API contracts, routers, schemas, or API smoke behavior.",
"exclusive": false
},
{
"name": "area/db",
"color": "0e8a16",
"description": "Database sessions, models, transactions, or persistence primitives.",
"exclusive": false
},
{
"name": "area/devex",
"color": "bfd4f2",
"description": "Local developer workflow, scripts, tests, tooling, or release helpers.",
"exclusive": false
},
{
"name": "area/release",
"color": "c2e0c6",
"description": "Versioning, release locks, tags, packaging, or dependency pins.",
"exclusive": false
},
{
"name": "area/security",
"color": "b60205",
"description": "Security posture, static analysis, supply-chain hardening, or vulnerability remediation.",
"exclusive": false
},
{
"name": "area/docs",
"color": "5319e7",
"description": "Durable documentation and project guidance.",
"exclusive": false
},
{
"name": "area/marketing",
"color": "f9d0c4",
"description": "Public website, product messaging, publication copy, or legal page content.",
"exclusive": false
},
{
"name": "source/todo-scan",
"color": "cccccc",
"description": "Imported from inline TODO/FIXME/HACK markers by the Gitea TODO importer.",
"exclusive": false
},
{
"name": "source/backlog-import",
"color": "bfdadc",
"description": "Imported from markdown backlog, roadmap, plan, or TODO files.",
"exclusive": false
},
{
"name": "source/security-audit",
"color": "d4c5f9",
"description": "Created from a structured security or code-quality audit report.",
"exclusive": false
},
{
"name": "audit/quick-fix",
"color": "0e8a16",
"description": "Audit finding that appears narrow and directly fixable.",
"exclusive": false
},
{
"name": "audit/structural",
"color": "d93f0b",
"description": "Audit finding that needs design, refactoring, or behavior review.",
"exclusive": false
},
{
"name": "audit/complexity",
"color": "fbca04",
"description": "Complexity finding from Radon, Xenon, or equivalent maintainability scans.",
"exclusive": false
},
{
"name": "audit/duplication",
"color": "c2e0c6",
"description": "Duplicated-code finding from jscpd or equivalent similarity scans.",
"exclusive": false
},
{
"name": "audit/false-positive",
"color": "cccccc",
"description": "Audit finding reviewed as a narrow false positive or acceptable risk.",
"exclusive": false
},
{
"name": "audit/needs-design",
"color": "f9d0c4",
"description": "Audit finding that needs an architectural or product decision before implementation.",
"exclusive": false
},
{
"name": "codex/ready",
"color": "0e8a16",
"description": "Suitable for Codex to pick up with the existing issue context.",
"exclusive": false
},
{
"name": "codex/needs-human",
"color": "f9d0c4",
"description": "Needs an explicit human decision before Codex should implement.",
"exclusive": false
}
]