[jacksonsr451]

Summary

Closes #44

Implements multi-repository project configuration for the EventFlow Work Management bounded context.

Projects can now be associated with multiple GitHub and GitLab repositories through stable remote identities, database-enforced deduplication, secure lifecycle management, and workspace-scoped authorization.

This PR establishes the domain and API foundation required for future GitHub and GitLab integration adapters (#27 and #28), without introducing remote synchronization or provider-side mutations.

Changes

Multi-Repository Project Configuration

Introduced ProjectRepositoryLink and the project_repositories persistence model.

Each project can maintain multiple remote repository associations across GitHub and GitLab.

Stable repository identity is defined by:

• workspace_id
• project_id
• provider
• provider_instance_id
• remote_repository_id

The provider instance identifies the hosting environment independently of installation IDs.

Repository names and URLs are treated as mutable metadata rather than authoritative identifiers.

Repository Identity and Deduplication

Implemented:

• GitHub and GitLab repository support.
• Provider-instance isolation.
• HTTPS, SSH, and SCP-style URL normalization.
• Canonical repository URL representation.
• Database-enforced uniqueness.
• Concurrent duplicate creation protection.
• Stable identity independent of URL formatting.
• Explicit duplicate and archived-association errors.

Duplicate associations return REPOSITORY_ALREADY_LINKED.

Archived repository identities cannot be silently re-linked and return 409 REPOSITORY_ARCHIVED.

Association Lifecycle

Supported states:

• active
• inactive
• archived

Supported operations:

• Create repository association.
• List associated repositories.
• Retrieve association details.
• Update repository metadata.
• Deactivate association.
• Reactivate association.
• Archive association.

Archival is terminal.

No remote repositories, branches, issues, or provider settings are modified.

REST API

Added five operations:

Method	Endpoint	Description
POST	/v1/workspaces/{workspace_id}/projects/{project_id}/repositories	Create association
GET	/v1/workspaces/{workspace_id}/projects/{project_id}/repositories	List associations
GET	/v1/workspaces/{workspace_id}/projects/{project_id}/repositories/{repository_id}	Retrieve association
PATCH	/v1/workspaces/{workspace_id}/projects/{project_id}/repositories/{repository_id}	Update association
DELETE	/v1/workspaces/{workspace_id}/projects/{project_id}/repositories/{repository_id}	Archive association

API capabilities include:

• Strong ETags.
• If-Match optimistic concurrency.
• HTTP 412 for stale preconditions.
• Optional Idempotency-Key for POST, PATCH, and DELETE.
• Durable idempotency records.
• Cursor-based pagination.
• Provider and status filters.
• include_archived filtering.
• Deterministic ordering.
• Explicit domain errors.

Updated OpenAPI and JSON Schema contracts with the ProjectRepository DTOs and Project repositories tag.

Authorization and Security

Repository configuration mutations require Workspace Owner or Admin privileges.

Read access requires authorized Workspace membership.

Security guarantees include:

• Workspace and Project isolation.
• Cross-tenant resource concealment using HTTP 404.
• Server-side RBAC enforcement.
• Rejection of embedded credentials and userinfo.
• Rejection of insecure HTTP repository URLs.
• Rejection of unsupported ports, queries, and fragments.
• Rejection of provider-host mismatches.
• No plaintext credentials or provider tokens in association records.

Audit Trail

Added append-only audit events:

• project_repository.linked
• project_repository.updated
• project_repository.deactivated
• project_repository.reactivated
• project_repository.unlinked

Audit records contain repository identity and lifecycle metadata without exposing credentials or secrets.

PostgreSQL Migration

Added migration:

0010_project_repositories

Parent revision:

0009_entity_collaboration

The migration introduces:

• project_repositories table.
• Composite Workspace/Project foreign key.
• uq_project_repositories_identity uniqueness constraint.
• Provider and lifecycle validation constraints.
• Verification and consistency constraints.
• Keyset pagination indexes.
• Remote identity lookup indexes.

Migration upgrade, repeated upgrade, and downgrade tests passed.

The required 0009_entity_collaboration migration is already present in the target branch.

Testing

All reported local validation checks passed.

Suite	Passed	Failed	Skipped
Work Management	193	0	1
Root contracts and security	114	0	0
Total	307	0	1

Nine new tests were added:

• Four URL normalization unit tests.
• Two repository metadata unit tests.
• Three PostgreSQL integration tests, including concurrent duplicate creation.

Additional validation:

• Contract validation passed.
• Pre-commit hooks passed.
• git diff --check passed.
• Migration upgrade/downgrade tests passed.
• Existing regression tests passed.
• Remote CI pending.
• Pull Request review pending.

The existing environment-dependent skipped test remains unchanged.

Acceptance Criteria

• Multiple repositories per Project.
• GitHub and GitLab support.
• Stable remote repository identity.
• Provider-instance isolation.
• Repository URL canonicalization.
• Database-enforced deduplication.
• Concurrent duplicate creation protection.
• Active/inactive/archive lifecycle.
• Authorized reactivation.
• Terminal archival.
• Workspace and Project isolation.
• RBAC enforcement.
• Durable idempotency.
• Optimistic concurrency.
• Append-only audit events.
• Updated OpenAPI and JSON Schema contracts.
• Updated documentation.
• Reproducible database migration.
• PostgreSQL integration tests.
• Order Processing bounded context preserved.

Scope Boundaries

This PR implements repository configuration only.

The following capabilities remain outside its scope:

• GitHub Issues/Projects synchronization ([FEAT] Integrar GitHub Issues e Projects por adaptador #27).
• GitLab Issues/Boards synchronization ([FEAT] Integrar GitLab Issues e Boards por adaptador #28).
• Provider API calls.
• Repository cloning.
• Branch inspection.
• Remote repository modifications.
• Webhook processing.
• External issue linking.
• Provider credential management.

Repository associations are configuration metadata, not evidence of an active provider connection or synchronization.

Known Limitations and Risks

Provider Verification

verification_status = verified remains unavailable until an authorized provider adapter performs remote verification.

Archived Associations

Archived repository identities cannot be re-linked.

Restoration would require a future explicit lifecycle decision and implementation.

Row-Level Security

PostgreSQL RLS remains deferred.

Tenant isolation currently depends on application-level authorization and Workspace-scoped queries.

Migration Downgrade

The migration supports downgrade, but downgrading is not data-preserving for repository associations.

Provider Synchronization

No GitHub or GitLab synchronization is introduced.

Clients must treat associations as configuration metadata only.

Review Focus

Please review:

1. Stable repository identity and uniqueness constraints.
2. Provider-instance isolation.
3. Repository URL normalization and validation.
4. Workspace and Project authorization.
5. Concurrent duplicate creation.
6. Durable idempotency behavior.
7. Strong ETag and If-Match enforcement.
8. Archive and reactivation semantics.
9. Audit consistency.
10. Migration upgrade/downgrade behavior.
11. Compatibility with future GitHub/GitLab adapters.

Git Information

Branch: feat/44-multi-repository-project-configuration

Base: origin/main at 17f8d4f

Commit:

bcccae2 feat(work-management): implement multi-repository project configuration (#44)

Working tree: Clean at the time of local validation.

Local verification: 307 passed, 0 failed, 1 skipped.

Final Status

READY FOR PR

Issue #44 has been implemented and verified locally.

The implementation provides a secure, provider-neutral, PostgreSQL-backed foundation for linking multiple GitHub and GitLab repositories to EventFlow Projects.

Remote CI verification and code review remain pending.