agent-skills/skills/git-control/SKILL.md

---

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:

{"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

5. 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

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)

# 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: Each line shows hash | author | message. When there are unmerged commits, a "By user (unmerged)" summary lists each user and their commit count.

7. 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)
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)