ken.li
2768d58aa3
- 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.
3.8 KiB
3.8 KiB
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:
{"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 |
.\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 |
.\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.
.\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.
.\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)
-ApiTokenor$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)