git-multibranch

name

git-multibranch

description

Guidance for setting up Git-based multi-branch deployment systems with SSH access, web servers, and automated deployment hooks. This skill should be used when configuring Git repositories that deploy to multiple environments (e.g., main/dev branches), setting up SSH authentication for Git, configuring web servers to serve content from different branches, or creating post-receive hooks for automated deployments.

Git Multi-Branch Deployment

Overview

This skill provides guidance for setting up Git-based deployment systems where multiple branches (e.g., main, dev) automatically deploy to different web server locations via post-receive hooks. It covers SSH configuration, Git repository setup, web server configuration, and automated deployment workflows.

Prerequisites Verification

Before starting, verify all required tools and configurations:

• Check for required packages: git, openssh-server, sshpass (for testing), web server (nginx/apache)
• Verify port availability for SSH (22) and HTTP/HTTPS (80/443)
• Confirm user creation permissions
• Set Git default branch name upfront: git config --global init.defaultBranch main

Approach: Step-by-Step Implementation

1. User and SSH Setup

Actions:

• Create a dedicated Git user with home directory
• Set password for SSH authentication
• Configure SSH to allow password authentication

SSH Configuration Considerations:

• Modify /etc/ssh/sshd_config settings: PasswordAuthentication yes, ChallengeResponseAuthentication yes
• Consider additional settings that may interfere: UsePAM, KbdInteractiveAuthentication
• Restart SSH service after configuration changes
• Plan for SSH host key verification in testing (either pre-accept keys or handle StrictHostKeyChecking)

2. Git Repository Creation

Actions:

• Create a bare Git repository in the Git user's home directory
• Initialize with proper permissions
• Create initial branches with content

Branch Setup Pattern:

1. Clone the bare repo to a temp location
2. Create initial commit on main branch
3. Create and populate additional branches (e.g., dev)
4. Push all branches to the bare repo

3. Web Server Configuration

Actions:

• Create deployment directories for each branch (e.g., /var/www/main, /var/www/dev)
• Set appropriate ownership and permissions for the Git user
• Configure virtual hosts or server blocks for each deployment target
• Handle SSL certificates if HTTPS is required

SSL Certificate Generation (self-signed):

• Use openssl req with appropriate subject and SAN extensions
• Configure web server to use the certificates with modern TLS protocols

4. Post-Receive Hook Creation

Actions:

• Create executable post-receive hook in hooks/ directory of bare repo
• Parse ref updates to determine which branch was pushed
• Checkout appropriate branch to corresponding deployment directory

Hook Structure:

1. Read stdin for ref updates (oldrev newrev refname)
2. Parse branch name from refname
3. For each target branch, checkout to deployment directory using GIT_WORK_TREE

5. Service Configuration

Actions:

• Start and enable required services (SSH, web server)
• Configure services to start on boot if persistence is needed
• Verify services are running and accessible

Verification Strategies

SSH Access Verification

• Test SSH connection with password: sshpass -p <password> ssh -o StrictHostKeyChecking=no <user>@<host>
• Verify Git operations over SSH work correctly

Git Operations Verification

• Clone the repository via SSH
• Create test commits and push to each branch
• Verify pushes complete without errors

Deployment Verification

• After each push, verify content appears in correct deployment directory
• Test web server serves correct content for each branch/endpoint
• Verify deployment completes within required time constraints

End-to-End Testing Pattern

1. Clone repository to fresh test directory
2. Make changes to branch content
3. Push changes
4. Immediately verify web endpoint reflects changes
5. Time the deployment if latency requirements exist

Common Pitfalls and Mistakes

Branch Naming Confusion

• Problem: Git may default to master instead of main
• Solution: Set git config --global init.defaultBranch main before creating repositories
• Recovery: Rename branch with git branch -m master main if already created

SSH Configuration Incomplete

• Problem: SSH connections fail despite configuration changes
• Causes: Missing settings like UsePAM, KbdInteractiveAuthentication, or service not restarted
• Solution: Verify all related SSH settings and restart sshd after changes

Host Key Verification Failures

• Problem: SSH commands fail with host key verification errors
• Solutions:
  • Pre-accept host keys: ssh-keyscan -H <host> >> ~/.ssh/known_hosts
  • Use StrictHostKeyChecking=no for testing (document security implications)

Push Conflicts During Testing

• Problem: Non-fast-forward errors when re-testing
• Causes: Previous test data conflicts with new pushes
• Solutions:
  • Use fresh test directories for each test run
  • Force-push if appropriate: git push --force
  • Reset repository state between tests

Post-Receive Hook Issues

• Problem: Hook doesn't execute or deployment fails silently
• Causes: Hook not executable, wrong shebang, missing GIT_WORK_TREE
• Verification: Add logging to hook, check permissions with ls -la hooks/

Service State Issues

• Problem: Services not running or not starting on boot
• Solution: Use systemctl enable for boot persistence, verify status before testing

Missing Prerequisites

• Problem: Commands fail because required tools not installed
• Solution: Check all prerequisites at the start, install missing packages before beginning setup

Edge Cases to Consider

Unhandled Branch Pushes

• Decide behavior when branches other than configured ones are pushed
• Document whether silent ignore, warning, or error is appropriate

Failed Deployments

• Consider adding error handling in post-receive hooks
• Decide on notification mechanism for deployment failures

Concurrent Pushes

• Be aware of potential race conditions with simultaneous pushes
• Consider adding locking mechanism for production environments

Permission Issues

• Ensure Git user has write access to all deployment directories
• Verify ownership after creating directories

Efficiency Recommendations

Reduce Repetition

• Set environment variables for repeated SSH commands: export GIT_SSH_COMMAND='sshpass -p password ssh -o StrictHostKeyChecking=no'
• Batch related operations into single shell invocations

Clean Testing

• Use isolated test directories that don't accumulate artifacts
• Clean up test repositories between runs

Command Availability

• Verify command existence before using (e.g., command -v time before timing operations)
• Have fallbacks ready (e.g., date +%s%3N instead of time)