PM-5925 - add challenge participants to gitea teams upon challenge registration

[vas3a]

https://topcoder.atlassian.net/browse/PM-5925

This pull request introduces comprehensive support for synchronizing Gitea teams with challenge registrants, including new API endpoints, configuration options, documentation, and extensive test coverage. The changes enable automatic addition and removal of challenge participants from Gitea teams, provide a new API to search for Gitea teams across organizations, and ensure robust error handling and configurability.

Key changes include:

Gitea Team Synchronization and API:

• Added a new API endpoint (GiteaTeamController and route /gitea/teams) to search for Gitea teams by name across configured organizations, with appropriate RBAC and OAuth scope checks. This endpoint supports filtering and limiting results, and qualifies team names by their organization. [1]], [2]], [3]], [4]], [5]])
• Introduced DTOs (GiteaTeamSearchQueryDto, GiteaTeamResponseDto) for input validation and response shaping in team search operations. ([src/dto/giteaTeam.dto.tsR1-R60])

Configuration and Environment:

• Added new environment variables (GITEA_AUTH_SOURCE_ID, GITEA_USER_VISIBILITY, GITEA_ORGANIZATIONS) to support Gitea account provisioning and team lookup. These are documented in .env.sample and docs/GITEA_WORKFLOW_SETUP.md, and parsed in a robust, deduplicating way in code. [1]], [2]], [3]], [4]])
• Updated CommonConfig to include Gitea-related configuration, including organizations to search for teams and authentication source details. ([src/shared/config/common.config.tsR79-R93])

Documentation:

• Added docs/GITEA_CHALLENGE_TEAM_SYNC.md to explain how challenge registrants are synced with Gitea teams, including configuration, Kafka topics, flow, and error handling. ([docs/GITEA_CHALLENGE_TEAM_SYNC.mdR1-R51])
• Updated workflow setup documentation to describe new environment variables and their roles. ([docs/GITEA_WORKFLOW_SETUP.mdR7-R13])

Testing and Robustness:

• Added comprehensive unit tests for Gitea team membership management (gitea-team-membership.service.spec.ts) and team search functionality (gitea.service.spec.ts), covering edge cases, error handling, and correct behavior. [1]], [2]])

Supporting Types and Logic:

• Defined new TypeScript interfaces for Gitea user provisioning and team search results, and implemented utility functions for parsing CSV environment variables. [1]], [2]])

These changes together enable seamless, configurable, and robust synchronization between challenge registration events and Gitea team memberships, while providing clear documentation and strong test coverage.

[Copilot]

Pull request overview

Adds end-to-end support for synchronizing Gitea team membership with challenge registrants (via Kafka resource events) and exposes a new API endpoint to search Gitea teams across configured organizations, backed by new config, docs, and tests.

Changes:

• Introduces Kafka handlers for challenge.action.resource.create/delete to add/remove submitters to/from Gitea teams configured on a challenge.
• Expands GiteaService with user provisioning, team membership operations, and cross-organization team search; adds /gitea/teams endpoint with RBAC + OAuth scope.
• Adds Gitea configuration fields/env docs plus new unit tests for team search and membership sync.

Reviewed changes

Copilot reviewed 18 out of 18 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
src/shared/modules/kafka/handlers/registered-handlers.config.ts	Registers new resource create/delete handlers.
src/shared/modules/kafka/handlers/challenge-resource-membership.handlers.spec.ts	Adds unit tests for the new Kafka handlers.
src/shared/modules/kafka/handlers/challenge-resource-membership.base.ts	Shared validation/filtering + error swallowing for membership handlers.
src/shared/modules/kafka/handlers/challenge-resource-delete.handler.ts	Implements unregistration -> remove from configured teams.
src/shared/modules/kafka/handlers/challenge-resource-create.handler.ts	Implements registration -> add to configured teams.
src/shared/modules/global/globalProviders.module.ts	Wires new membership service and handlers into global providers.
src/shared/modules/global/gitea.service.ts	Adds user lookup/provisioning, team membership calls, and team search.
src/shared/modules/global/gitea.service.spec.ts	Tests Gitea team search behavior across orgs and failure modes.
src/shared/modules/global/gitea-team-membership.service.ts	Implements challenge metadata -> team resolution and per-team sync logic.
src/shared/modules/global/gitea-team-membership.service.spec.ts	Tests membership sync, provisioning flow, and metadata parsing edge cases.
src/shared/enums/scopes.enum.ts	Adds read:gitea-team OAuth scope.
src/shared/config/common.config.ts	Adds Gitea-related configuration and CSV parsing helper.
src/dto/giteaTeam.dto.ts	Adds DTOs for team search query validation and response typing.
src/api/gitea-team/gitea-team.controller.ts	Adds GET /gitea/teams controller with roles + scope checks.
src/api/api.module.ts	Registers the new controller in the API module.
docs/GITEA_WORKFLOW_SETUP.md	Documents new Gitea env vars for provisioning and team search.
docs/GITEA_CHALLENGE_TEAM_SYNC.md	Documents Kafka topics and sync flow for challenge team membership.
.env.sample	Adds sample values for new Gitea env vars.

Suppressed comments (2)

docs/GITEA_CHALLENGE_TEAM_SYNC.md:16

• This section documents character rules for team ids, but the code actually expects a positive integer team id (or numeric string) and skips anything else. Keeping the current text is misleading for operators debugging why a team is skipped.

A Gitea team id may only contain alphanumeric characters, dashes (`-`),
underscores (`_`) and dots (`.`).

docs/GITEA_CHALLENGE_TEAM_SYNC.md:20

• The doc says teams are skipped when they contain invalid characters, but the implementation skips entries that don’t contain a usable positive integer id. Updating this wording will better match the actual validation behavior.

Team ids are not validated when the challenge is saved. Values that contain any
other character, or that point at teams which do not exist, are logged and
skipped here.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[kkartunov]

Looks good.
@vas3a you will need to create new LB record for using v6/gitea* and point it to review API. Or move this to another path which exists. I am fine either way, let me know...