Update Repository Compliance Overview Workflow

[hdamker]

Parent Issue: #38 (Three Reporting Workflows Strategy)

Problem description

The Repository Compliance Overview workflow exists but is not actively used and needs updates. Currently it only checks API repositories with 9-point template compliance and runs only on manual trigger. We need comprehensive repository health and compliance monitoring across ALL CAMARA repositories with category-specific checks.

Current workflow: camaraproject/project-administration/.github/workflows/project-report-camara-repository-overview.yml (v1.1, July 2025)

Possible evolution

1. Expand Repository Scope

Current: Only API repositories (filtered by topics: sandbox-api-repository, incubating-api-repository, graduated-api-repository)

Proposed: All CAMARA repositories with category-specific checks (API repositories, Working Group repositories, Project Infrastructure repositories, Other/unknown repositories flagged for categorization)

2. Configuration-Driven Repository Registry (Hybrid Approach)

Introduce hybrid registry with two files:

repository-registry.yaml (Manual, source of truth):

repositories:
  - name: QualityOnDemand
    category: api-incubating
    sub_project: connectivity-quality-management
    required_maintainers: 3
    branch_protection_required: true
  - name: ReleaseManagement
    category: working-group
    required_maintainers: 2
    branch_protection_required: true

repository-state.yaml (Auto-generated, current snapshot):

repositories:
  - name: QualityOnDemand
    topics: [incubating-api-repository, qod, quality-of-service]
    description: "Quality on Demand API..."
    license: Apache-2.0
    last_activity: 2025-11-15
    maintainers_count: 5

Benefits: Clear policy expectations (registry defines what SHOULD be), automatic drift detection (state captures what IS), audit trail via state file PRs, community-accessible (non-admins can create registry PRs)

3. Enhanced Report Structure

Current: Single markdown report, 90-day artifact retention

Options: Separate reports by category, health score dashboard (0-100), severity-based violations (Critical/High/Medium/Low), multiple export formats (Markdown/JSON/CSV), persistent storage option

4. Separation of Concerns

• Repository Compliance (this workflow): Repository structure, governance files, configuration, templates
• API/Content Validation (separate CI/linting): OpenAPI spec validation, naming conventions
• Release Progress (separate workflow): Release readiness, API maturity tracking

Check Categories (high-level):

• Repository Configuration (topics, description, license, branch protection, visibility)
• Governance Files (CODEOWNERS, MAINTAINERS, GOVERNANCE.MD, LICENSE)
• Documentation Structure (README, CHANGELOG, directory structure, wiki links)
• Process Templates (issue templates, PR template, workflows)
• Activity and Health (last activity, stale issues/PRs, responsiveness, contributor diversity)

Detailed check definitions and requirements document will be created in a sub-issue.

Integration with Repository Lifecycle

The registry integrates with existing workflows:

• Repository Creation: Registry PR → project-admin-api-repository-creation.yml → Compliance validates
• Repository Promotion: Registry PR updates category/requirements → Settings updated → Compliance validates
• Repository Renaming: Registry PR updates name → GitHub rename → State auto-updates
• Repository Archiving: Registry PR marks archived → Different compliance rules apply

Future: Registry PR could trigger automated repository configuration changes

Alternative solution

To be discussed.

Additional context

Implementation approach:

1. Create sub-issue for detailed requirements document and check definitions
2. Design repository-registry.yaml schema and populate with known repositories
3. Implement repository-state.yaml generation (auto-discovery and snapshot)
4. Phase 1: Core governance checks (CODEOWNERS, MAINTAINERS, LICENSE, topics validation)
5. Phase 2: Enhanced reporting (health scores, severity categorization, drift detection)
6. Phase 3: Activity metrics and trend analysis

[wrathwolf]

Thanks for putting this together, Herbert. I think this proposal is already a really good start, and a lot of what's needed is either collected today or close to it. Sharing a few thoughts on attributes I'd like to see represented, mostly building on what you have rather than replacing it.

lifecycle_stage and sub_project are probably the two most important, since together they answer the questions that are hardest to determine from the wiki or GitHub today: what is this repository, and where does it sit in the project.

lifecycle_stage

Example values: proposal, sandbox-independent, sandbox-subproject, incubating, graduated, archived.

This overlaps with the category concept in your proposal, but I wonder if it's worth separating the two. category would describe what kind of thing the repo is (API, working group, project infrastructure, project governance, etc.), and lifecycle_stage would describe where it is in its lifecycle. That split lets us cleanly express things like "working group repo" without needing to force it into an API-oriented stage, and it gives us a natural place to hang a proposal state for incoming APIs and projects before they're formally created.

sub_project

Example values: the slug of a Sub Project, or independent for standalone sandboxes, or values like working-group / infrastructure / null for non-API repos.

Beyond governance reporting, this is what should drive wiki nesting. Today it's implicit in where the page sits in the tree, which is part of why the current ambiguity exists. Making it an explicit field means wiki pages know exactly where to land and how to cross-link.

api_names

A list of APIs hosted in the repo, empty for non-API repos.

Looking at the example in the proposal, the topics field mixes two different things: a repository classification (incubating-api-repository) and what looks like API identifiers (qod, quality-of-service). I think it's worth pulling the API identifiers out into their own structured field, since a repo can host multiple APIs (KnowYourCustomer and DeviceStatus are good examples) and we'll want to do joins against them. api_names is a placeholder name, I'm not attached to it, but the idea is to make this the explicit join back to config/api-landscape.yaml. That leaves topics free to be whatever freeform tagging is useful without having to double as structured data.

last_activity

Very helpful for spotting repos going stale early, so we can keep members and partners informed if they're relying on something that's losing momentum. Would pair well with the "Clean-up Process for Inactive Onboarding Trackers and Repositories" proposal already circulating in RM.

mailing_list

Not in the current proposal, but worth having. Useful for generated page headers and for automated outreach when something changes.

maintainers_count

Good attribute, though worth clarifying whether it's active or total. I think active is the more useful signal (again for staleness detection), with total available separately if we need it. I'm less sure about required_maintainers as a per-repo field. Since the requirement is driven by category (three for API repos, two for working group repos, etc.), it might fit better as a rule keyed by category in a small companion file, rather than repeated on every repo entry.

One broader note on tying this to existing data

Since a lot of this would be adjacent to config/api-landscape.yaml, config/meta-release-mappings.yaml, and the auto-generated data/releases-master.yaml, it would be worth making the join between them explicit. A simple back-reference (repository: on each API entry in api-landscape.yaml) would let CI validate that every API points at a real repo entry, and that every repo with api_names lists APIs that actually exist in the landscape. That turns drift into a CI failure instead of something we find out about later.

[hdamker]

@wrathwolf unfortunately is the issue description above and the issue itself outdated and does not reflect anymore my current thinking, I plan to close it and replace by a new issue.

My current thinking is more about a declarative central config file defining the repositories and then one (or more workflows) which reconcile the repository settings (even for new repositories). I suppose that will fit quite well with your problem and intention (a source of truth, used to set up repositories AND wiki pages).

But I see that the AI mixed also declarative fields with collected data & statistics. I recommend that you write one or two own issue(s) which are describing the problems you want to solve, with potential evolution. But please don't base on the above described workflow which I don't plan anymore to implement. Split the issue also in declarative (source of truth) data and collected data.

---

Said this, I see currently the following declarative attributes for repositories (naming to be decided, please don't rely on them):

• repository type
• lifecycle state (for API repositories only, following the Governance documents, no proposals as far as I see it)
• sub_project (or working group, as some repositories under working groups)
• mailing_list (can be null during bootstrap, but needed in repositories)
• wiki_page (can be null during bootstrap, but needed in repositories)
• configuration files which need to be kept current (e.g. workflows, .gitattribute, .editorconfig, ...), with defaults for repository types, and per repository overwrite if needed

Other data is defined within the repositories and will stay there:

• codewoners & maintainers (but we can think about a more machine readable format which is at the same time human oriented)
• release-metadata - collected within release-master.yaml, enriched with data from the config files
• release-plan - collected by Release Progress Tracker, combined with current release process state. The workflow and data is owned by ReleaseManagement
• the last two contain also the truth about the APIs in the repositories (released ones and planned ones), the api-landscape adds only additional data but does not define which APIs are in the repositories.

As it won't be a collector but a declarative system, I don't see the following points:

• last activity: expensive to collect, low value without further judgement (e.g. automated and chore issues/PR vs real content work)
• "active" maintainers, which I suppose is not measurable from GitHub activities (meeting participation, mails, ... ) - typically mainly the codeowners are active in reviews etc

[wrathwolf]

Thanks Herbert. We briefly discussed this on our call, so keeping it short.

Your move toward a declarative reconciliation model makes sense and aligns well with improving discoverability of project and API status across CAMARA. I'll open a separate issue focused on that discoverability problem so you can close this one when your replacement is ready.