onshoreoutsourcing Git Safe Operations
Wrapper for common git operations with safety checks, validation, and rollback support via Git MCP server.
Quick Start
Create branch safely:
"Create feature branch feature-1.10-infrastructure from epic-1-progressive-coherence"
Commit with validation:
"Commit changes for wave 1.10.1 with message 'Implement catalog change monitor'"
Merge with checks:
"Merge feature-1.10-infrastructure into epic-1-progressive-coherence"
Core Operations
Operation 1: Create Branch
Purpose: Create new branch with validation
Pre-Checks:
- ✅ Source branch exists
- ✅ Target branch name doesn't already exist
- ✅ Source branch is appropriate (development, epic, or feature)
- ✅ Branch name follows conventions
MCP Operation:
mcp__git__create_branch(
branch_name: "feature-1.10-infrastructure",
from_branch: "epic-1-progressive-coherence"
)
Post-Validation:
- Branch created successfully
- Branch pushed to remote
- Branch tracks remote
Rollback: Delete branch if creation fails partially
Operation 2: Commit Changes
Purpose: Commit staged changes with validation
Pre-Checks:
- ✅ On correct branch (not main)
- ✅ Changes are staged
- ✅ Commit message follows conventions
- ✅ No merge conflicts
MCP Operation:
mcp__git__commit(
message: "feat(wave-1.10.1): Implement catalog change monitor",
files: ["src/catalog/monitor.ts", "tests/monitor.test.ts"]
)
Post-Validation:
- Commit created successfully
- Commit has expected files
- Commit author correct
Rollback: Soft reset to HEAD~1 if commit has issues
Operation 3: Push Changes
Purpose: Push commits to remote with validation
Pre-Checks:
- ✅ Branch has commits to push
- ✅ Branch tracks remote
- ✅ Not pushing to main directly
- ✅ No conflicts with remote
MCP Operation:
mcp__git__push(
branch: "feature-1.10-infrastructure",
force: false,
set_upstream: true
)
Post-Validation:
- Push succeeded
- Remote branch updated
- No errors
Rollback: Force push previous state if needed (with confirmation)
Operation 4: Merge Branches
Purpose: Merge branches with conflict detection
Pre-Checks:
- ✅ Source branch has commits
- ✅ Target branch exists
- ✅ No uncommitted changes
- ✅ Branches can be merged (no conflicts)
MCP Operation:
mcp__git__merge(
source_branch: "feature-1.10-infrastructure",
target_branch: "epic-1-progressive-coherence",
strategy: "squash" # or "merge", "rebase"
)
Conflict Handling:
- If conflicts detected, abort merge
- Return conflict details to user
- Suggest resolution steps
Post-Validation:
- Merge completed successfully
- No conflicts remain
- All tests pass (if applicable)
Rollback: Abort merge if conflicts occur
Operation 5: Create Pull Request
Purpose: Create PR with validation
Pre-Checks:
- ✅ Source branch exists and pushed
- ✅ Target branch exists
- ✅ PR doesn't already exist
- ✅ Branch relationship valid (per branching strategy)
Operation (via gh CLI or GitHub API):
gh pr create \
--base epic-1-progressive-coherence \
--head feature-1.10-infrastructure \
--title "Feature 1.10: Infrastructure Complete" \
--body "Completed waves 1.10.1, 1.10.2, 1.10.3"
Validation:
- PR follows branching strategy
- No PR from feature → main (must go through development)
- PR has description
Post-Validation:
- PR created successfully
- PR checks triggered
- PR URL returned
Operation 6: Switch Branch
Purpose: Switch branches safely
Pre-Checks:
- ✅ Target branch exists
- ✅ No uncommitted changes (or stash option)
- ✅ Not currently on target branch
MCP Operation:
mcp__git__checkout(
branch: "development"
)
Post-Validation:
- Switched to target branch
- Working directory clean
- Branch up-to-date with remote
Operation 7: Delete Branch
Purpose: Delete branch safely
Pre-Checks:
- ✅ Branch is merged (or force flag provided)
- ✅ Not currently on branch to delete
- ✅ Not deleting main or development
- ✅ Confirmation provided
MCP Operation:
mcp__git__delete_branch(
branch: "feature-1.10-infrastructure",
force: false,
remote: true
)
Post-Validation:
- Branch deleted locally
- Branch deleted from remote
- No orphaned branches
Safety Checks
Pre-Operation Validation
Branch Protection Check:
def validate_branch_protection(branch_name):
"""Prevent operations on protected branches."""
if branch_name == "main":
return {
"allowed": False,
"reason": "Cannot perform direct operations on main branch"
}
return {"allowed": True}
Branch Naming Check:
def validate_branch_name(branch_name, branch_type):
"""Validate branch name follows conventions."""
patterns = {
"epic": r"^epic-\d+-[a-z0-9-]+$",
"feature": r"^feature-\d+\.\d+-[a-z0-9-]+$",
"wave": r"^wave-\d+\.\d+\.\d+-[a-z0-9-]+$",
"hotfix": r"^hotfix-[a-z0-9-]+$"
}
if not re.match(patterns[branch_type], branch_name):
return {
"valid": False,
"reason": f"Branch name doesn't match {branch_type} pattern",
"expected_pattern": patterns[branch_type]
}
return {"valid": True}
Commit Message Check:
def validate_commit_message(message):
"""Validate commit message follows conventional commits."""
pattern = r"^(feat|fix|docs|style|refactor|test|chore)(\(.+\))?: .+"
if not re.match(pattern, message):
return {
"valid": False,
"reason": "Commit message doesn't follow conventional commits format",
"expected_format": "type(scope): description"
}
return {"valid": True}
Post-Operation Validation
Verify Operation Success:
def verify_branch_created(branch_name):
"""Verify branch was created successfully."""
result = mcp__git__list_branches()
if branch_name not in result["branches"]:
return {
"success": False,
"reason": "Branch not found after creation"
}
return {"success": True}
Verify Remote Sync:
def verify_remote_sync(branch_name):
"""Verify branch is synchronized with remote."""
local_sha = mcp__git__get_branch_sha(branch=branch_name)
remote_sha = mcp__git__get_branch_sha(branch=f"origin/{branch_name}")
if local_sha != remote_sha:
return {
"synchronized": False,
"local_sha": local_sha,
"remote_sha": remote_sha
}
return {"synchronized": True}
Rollback Support
Rollback Scenarios
1. Branch Creation Failed
def rollback_branch_creation(branch_name):
"""Delete branch if creation failed partially."""
try:
mcp__git__delete_branch(branch=branch_name, force=True)
return {"rollback": "success", "message": "Branch deleted"}
except Exception as e:
return {"rollback": "failed", "error": str(e)}
2. Commit Has Issues
def rollback_commit():
"""Undo last commit if it has issues."""
mcp__git__reset(mode="soft", target="HEAD~1")
return {"rollback": "success", "message": "Commit undone, changes staged"}
3. Push Failed
def rollback_push(branch_name, previous_sha):
"""Reset branch to previous state before push."""
mcp__git__reset(mode="hard", target=previous_sha)
mcp__git__push(branch=branch_name, force=True)
return {"rollback": "success", "message": f"Branch reset to {previous_sha}"}
4. Merge Has Conflicts
def rollback_merge():
"""Abort merge if conflicts occur."""
mcp__git__merge_abort()
return {"rollback": "success", "message": "Merge aborted, working directory restored"}
Operation Examples
Example 1: Create Epic Branch
Scenario: Start new epic from development
Operation:
## Create Epic Branch: epic-1-progressive-coherence
**Pre-Checks**:
- ✅ Currently on development branch
- ✅ Development branch is clean (no uncommitted changes)
- ✅ Development branch up-to-date with remote
- ✅ Epic branch name follows convention: `epic-\d+-[a-z0-9-]+`
**MCP Operations**:
1. Create branch from development
mcp__git__create_branch( branch_name: "epic-1-progressive-coherence", from_branch: "development" )
2. Push branch to remote
mcp__git__push( branch: "epic-1-progressive-coherence", set_upstream: true )
**Post-Validation**:
- ✅ Branch created locally
- ✅ Branch pushed to remote
- ✅ Branch tracks origin/epic-1-progressive-coherence
- ✅ Currently on epic-1-progressive-coherence branch
**Result**: SUCCESS - Epic branch created and ready for features
Example 2: Commit Wave Implementation
Scenario: Commit completed wave to feature branch
Operation:
## Commit Wave 1.10.1 Implementation
**Pre-Checks**:
- ✅ Currently on feature-1.10-infrastructure branch
- ✅ Changes staged (2 files modified)
- ✅ No merge conflicts
- ✅ Commit message follows convention: `feat(wave-1.10.1): ...`
**MCP Operations**:
1. Verify staged changes
mcp__git__status()
Output: 2 files staged
2. Create commit
mcp__git__commit( message: "feat(wave-1.10.1): Implement catalog change monitor", files: ["src/catalog/monitor.ts", "tests/monitor.test.ts"] )
3. Push commit
mcp__git__push(branch: "feature-1.10-infrastructure")
**Post-Validation**:
- ✅ Commit created with correct message
- ✅ Commit contains expected files
- ✅ Commit pushed to remote
- ✅ Remote branch updated
**Result**: SUCCESS - Wave 1.10.1 committed and pushed
Example 3: Merge Feature to Epic
Scenario: Merge completed feature branch to epic
Operation:
## Merge feature-1.10-infrastructure → epic-1-progressive-coherence
**Pre-Checks**:
- ✅ Feature branch has all waves committed
- ✅ Feature branch pushed to remote
- ✅ No uncommitted changes
- ✅ Epic branch exists
- ✅ No merge conflicts detected
**MCP Operations**:
1. Switch to epic branch
mcp__git__checkout(branch: "epic-1-progressive-coherence")
2. Pull latest from remote
mcp__git__pull(branch: "epic-1-progressive-coherence")
3. Merge feature branch
mcp__git__merge( source_branch: "feature-1.10-infrastructure", target_branch: "epic-1-progressive-coherence", strategy: "merge" )
4. Push merge
mcp__git__push(branch: "epic-1-progressive-coherence")
**Post-Validation**:
- ✅ Merge completed without conflicts
- ✅ All feature commits in epic branch
- ✅ Epic branch pushed to remote
- ✅ Feature branch can be deleted
**Result**: SUCCESS - Feature merged to epic
Example 4: Create Pull Request
Scenario: Create PR from development to main
Operation:
## Create PR: development → main
**Pre-Checks**:
- ✅ Development branch pushed to remote
- ✅ Development has commits ahead of main
- ✅ No existing PR from development to main
- ✅ Branch relationship valid (development → main allowed)
- ✅ PR branch check workflow will pass
**Operation**:
```bash
gh pr create \
--base main \
--head development \
--title "Release: Sprint 5.1 Complete" \
--body "## Summary
Completed waves:
- Wave 1.10.1: Catalog change monitor
- Wave 1.10.2: Template staleness detection
- Wave 1.10.3: Impact analysis
## Testing
All tests passing, ready for release."
Post-Validation:
- ✅ PR created successfully
- ✅ PR checks triggered (check-source-branch)
- ✅ PR URL: https://github.com/org/repo/pull/123
- ✅ PR ready for review
Result: SUCCESS - PR #123 created
---
## Integration with Workflow
### Before Every Git Operation
1. Invoke `git-repository-setup-validation` (if not already done)
2. Verify repository properly configured
3. Use `git-safe-operations` for all git commands
4. Validate operation before executing
### During Development
1. Use safe operations for branch creation
2. Use safe operations for commits
3. Use safe operations for merges
4. Get rollback support automatically
### Error Handling
```markdown
If safe operation fails:
1. Check error message from skill
2. Review pre-check failures
3. Fix issues (e.g., uncommitted changes)
4. Retry operation
5. If still failing, use rollback
Available Resources
Scripts
- scripts/safe_branch_create.py — Create branch with validation
- scripts/safe_commit.py — Commit with validation
- scripts/safe_merge.py — Merge with conflict detection
- scripts/safe_push.py — Push with validation
References
- references/git-operation-patterns.md — Common operation patterns
- references/rollback-procedures.md — How to rollback operations
- references/error-codes.md — Error codes and solutions
Success Criteria
- ✅ Operation validated before execution
- ✅ Operation executed via Git MCP server
- ✅ Post-validation confirms success
- ✅ Rollback available if needed
- ✅ Clear error messages on failure
- ✅ Audit trail maintained
Tips for Safe Operations
- Always validate first - Use pre-checks before operations
- Use MCP server - Don't bypass with raw git commands
- Commit frequently - Smaller commits easier to rollback
- Push after commits - Keep remote synchronized
- Test merge locally - Check for conflicts before PR
- Follow conventions - Branch names and commit messages
- Use rollback - Don't be afraid to undo and retry
Common Issues and Solutions
Issue 1: Branch Already Exists
Problem: Trying to create branch that already exists Solution: Use different branch name or delete existing branch first
Issue 2: Uncommitted Changes
Problem: Can't switch branches with uncommitted changes Solution: Commit changes, stash changes, or discard changes
Issue 3: Merge Conflicts
Problem: Merge has conflicts that can't auto-resolve Solution: Abort merge, resolve conflicts manually, retry merge
Issue 4: Push Rejected
Problem: Remote has commits not in local Solution: Pull from remote, merge/rebase, then push
Issue 5: Invalid Branch Name
Problem: Branch name doesn't follow conventions Solution: Rename branch to match convention pattern
Last Updated: 2025-01-30