Project onboarding: one idempotent API operation with automated checks and a documented external-request pattern

[coopernetes]

Summary

Onboarding a new upstream project today means an administrator adding an access rule and granting permissions by hand, or an organisation building automation against the REST API to do it from a request form. fogwall should support the second pattern as a first-class, documented flow rather than leaving each organisation to discover the endpoints.

Wanted

• One idempotent onboarding operation through the API that, for a provider and repository, creates the access rule, provisions the requesting user if needed, and assigns the initial grants in a single call with a single audit record. Re-running it converges rather than duplicating.
• Automated checks run as part of that operation and are reported in the result: the repository's licence against the licence rules in feat: LICENSE-based allow rules — permit access to upstream repos by license type #220, its visibility, and whether it already matches an existing rule.
• A documented reference pattern in the admin guide for driving onboarding from an external request system (a form or issue template that triggers automation calling this API), including the scoped credential such automation should use.
• Where feat: LICENSE-based allow rules — permit access to upstream repos by license type #220 already permits the repository by licence, onboarding is unnecessary for access and the operation reports that, so per-repository onboarding is reserved for repositories the licence rules do not cover.

Boundaries

• The request and approval workflow itself stays outside fogwall; fogwall provides the operation and the checks, not the form.
• Grants created this way are ordinary grants and are managed afterwards like any other.
• Depends on Machine-to-machine API auth: OAuth2 resource server + API key management #57 for a credential the automation can hold that is scoped to onboarding rather than full admin.