feat(git-control): add Git repository and branch access control features

- Introduced new scripts for managing Gitea repository permissions, including branch protection, user access, and organization-wide settings. - Added documentation for the git-control skill, detailing API usage and capabilities. - Included .gitignore to prevent committing sensitive configuration files. - Created references for Gitea API endpoints related to branch protection and user permissions.
2026-02-27 14:16:36 +08:00
parent a5840ed7c6
commit 2768d58aa3
10 changed files with 429 additions and 20 deletions
@@ -0,0 +1,105 @@
+---
+name: git-control
+description: Gitea repository and branch access control. Use when managing Git permissions: enable/disable branch protection (push, merge, read), user read/write permissions on repos, organization-wide repo access, listing orgs/repos, or bulk permission changes. Supports Gitea API (e.g. afe.git:3000).
+---
+
+# Git Control (Gitea)
+
+Control Gitea repository and branch permissions via API. Requires Gitea API Token with admin/repo permissions.
+
+**API Reference**: See `references/gitea_api.md` for endpoints.
+
+## Prerequisites
+
+- **Gitea API Token**: Settings → Applications → Generate New Token (repo, admin for org-level)
+- **Base URL**: Default `http://afe.git:3000` (override with `-GiteaBaseUrl`)
+
+**Local config**: Scripts auto-load from `config.local.json` in the skill root when ApiToken is not provided. Format:
+```json
+{"ApiToken": "your-token", "GiteaBaseUrl": "http://afe.git:3000"}
+```
+
+## Capabilities
+
+### 1. Branch Protection (Enable/Disable)
+
+Control who can push or merge to a branch.
+
+| Action | Script | Effect |
+|--------|--------|--------|
+| Lock branch (read-only) | `branch_protect.ps1 -Action lock` | No push, no merge |
+| Unlock branch | `branch_protect.ps1 -Action unlock` | Remove protection |
+| Restrict merge only | `branch_protect.ps1 -Action merge-only` | No direct push, PR merge allowed |
+
+```powershell
+.\scripts\branch_protect.ps1 -ApiToken "..." -Owner G3SF -Repo g3fo-trade -BranchName uat -Action lock
+```
+
+### 2. List Orgs & Repos
+
+| Action | Script |
+|--------|--------|
+| List all organizations | `list_orgs_repos.ps1 -Action list-orgs` |
+| List repos in org | `list_orgs_repos.ps1 -Action list-repos -Org G3SF` |
+| List all repos (admin) | `list_orgs_repos.ps1 -Action list-all-repos` |
+
+### 3. User Repo Permissions
+
+Add, remove, or change a user's permission on a repo.
+
+| Action | Effect |
+|--------|--------|
+| Grant read | User can view only |
+| Grant write | User can push, create PRs |
+| Grant admin | User can manage settings |
+| Revoke | Remove collaborator |
+
+```powershell
+.\scripts\user_permission.ps1 -ApiToken "..." -Owner G3SF -Repo g3fo-trade -Username john -Action read
+.\scripts\user_permission.ps1 -ApiToken "..." -Owner G3SF -Repo g3fo-trade -Username john -Action revoke
+```
+
+### 4. Org-Wide Repo Protection
+
+Apply branch protection to all repos under an organization.
+
+```powershell
+.\scripts\org_repos_protect.ps1 -ApiToken "..." -Org G3SF -BranchName uat -Action lock
+```
+
+### 5. Org-Wide User Access
+
+Revoke or grant a user's collaborator access across all org repos.
+
+```powershell
+.\scripts\org_user_access.ps1 -ApiToken "..." -Org G3SF -Username john -Action revoke
+.\scripts\org_user_access.ps1 -ApiToken "..." -Org G3SF -Username john -Action read
+```
+
+Note: Org repos often use team permissions. For team-based access, use Gitea API team endpoints (see `references/gitea_api.md`).
+
+## Common Control Functions
+
+| Function | Description |
+|----------|-------------|
+| **Lock UAT for release** | Lock `uat` branch on specified repos before release freeze |
+| **Unlock for merge** | Temporarily allow merge (add user to merge allowlist) |
+| **Audit user access** | List repos a user can access (collaborators + org teams) |
+| **Bulk branch lock** | Lock same branch across multiple repos |
+| **Read-only maintenance** | Set repo to read-only during maintenance |
+| **New member onboarding** | Grant read to org repos for new team member |
+| **Offboarding** | Revoke user from all org repos |
+
+## Script Parameters (Common)
+
+- `-ApiToken` or `$env:GITEA_TOKEN`
+- `-GiteaBaseUrl` (default: http://afe.git:3000)
+- `-Owner` / `-Org` (organization name)
+- `-Repo` (repository name)
+- `-BranchName` (branch pattern, e.g. uat, main)
+
+## Error Handling
+
+- 403: Insufficient permissions (need admin for org ops)
+- 404: Repo/org/user not found
+- 422: Validation error (check API compatibility with Gitea version)