142 lines
5.5 KiB
Markdown
142 lines
5.5 KiB
Markdown
---
|
|
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, bulk permission changes, or comparing branches to detect unmerged commits (e.g. prod hotfix not in main). 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
|
|
```
|
|
|
|
### 5. 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
|
|
```
|
|
|
|
### 6. Branch Compare (Detect Unmerged Commits)
|
|
|
|
Analyze differences between branches to find commits that need merging (e.g. prod hotfix not merged to main).
|
|
|
|
| Mode | Script | Use Case |
|
|
|------|--------|----------|
|
|
| Single repo (local) | `branch_compare.ps1 -RepoPath` | Repo cloned locally |
|
|
| Single repo (API) | `branch_compare.ps1 -Owner -Repo` | No local clone |
|
|
| Single repo | `org_branch_compare.ps1 -Repo g3fo-trade` | One repo by name |
|
|
| Org-wide | `org_branch_compare.ps1` | All repos in org |
|
|
|
|
**CompareSet**:
|
|
- `single`: BaseBranch vs HeadBranch only (default for branch_compare)
|
|
- `full`: main vs uat, main vs prod, uat vs prod (default for org_branch_compare)
|
|
|
|
```powershell
|
|
# Single repo - full check (main/uat/prod)
|
|
.\scripts\branch_compare.ps1 -RepoPath "d:\path\to\g3fo-trade" -CompareSet full
|
|
.\scripts\branch_compare.ps1 -Owner G3SF -Repo g3fo-trade -CompareSet full
|
|
|
|
# Single pair
|
|
.\scripts\branch_compare.ps1 -RepoPath "d:\path\to\repo" -BaseBranch main -HeadBranch uat
|
|
|
|
# Single repo by name (org)
|
|
.\scripts\org_branch_compare.ps1 -Org G3SF -Repo g3fo-trade -CompareSet full
|
|
|
|
# All G3SF repos - full check
|
|
.\scripts\org_branch_compare.ps1 -Org G3SF -CompareSet full -WorkspaceRoot "d:\AFE Git\G3SF\G3FO\server"
|
|
|
|
# Filter by date or tag
|
|
.\scripts\branch_compare.ps1 -RepoPath "d:\path\to\repo" -CompareSet full -SinceDate "2025-01-01"
|
|
```
|
|
|
|
**Output**: Commits in `HeadBranch` NOT in `BaseBranch` = need to merge (hotfixes). Commits in `BaseBranch` NOT in `HeadBranch` = base is ahead (normal).
|
|
|
|
### 7. 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) |
|
|
| **Detect unmerged hotfixes** | Compare prod vs main to find commits in prod not in main |
|
|
| **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)
|