Git Workflow¶

Version: Arctyk ITSM v0.6.0+
Last Updated: January 2026

Git branching strategy and workflow for Arctyk ITSM.

Branches¶

main - Production-ready code
feature/* - New features
fix/* - Bug fixes

Workflow¶

Create branch from main
Make changes
Push branch
Open pull request
Code review
Merge to main

Git Push & Deploy Workflow Guide¶

Overview¶

Your project uses GitHub Actions to automatically test and deploy when you push to the main branch.

Branch Structure¶

main: Production branch - triggers tests + deployment to Droplet
dev: Development branch - triggers tests only
Feature branches: For development work

Step-by-Step: Push to Production¶

1. Make Your Changes¶

# Edit files as needed
# Save your work

2. Check Status¶

git status
# Shows: modified files, staged files, current branch

3. Stage Your Changes¶

# Stage specific files
git add src/users/templates/users/partials/user_history.html
git add src/tickets/templates/tickets/partials/ticket_history.html

# OR stage everything
git add .

4. Commit Your Changes¶

git commit -m "fix: add null check for changed_by in history templates"
# Use conventional commits: feat:, fix:, chore:, docs:, refactor:, test:

5. Push to GitHub¶

git push origin main
# This triggers GitHub Actions workflow

6. Monitor Deployment¶

Go to: https://github.com/your-username/arctyk-itsm/actions Watch the CI/CD Pipeline run:

Test job: Runs pytest suite (~60 seconds)
Build-and-deploy job: Builds Docker image, pushes to DockerHub, deploys to Droplet (~3-5 minutes)

What Happens on Push to Main¶

GitHub Actions Triggers (ci-cd.yml)
Runs on: push to main branch only
Test Job (Always runs)
Spins up PostgreSQL 17 + Redis 7
Installs Python 3.13 + dependencies
Runs migrations
Runs pytest with coverage
Uploads coverage to Codecov
Build-and-Deploy Job (Only if tests pass)
Extracts version from pyproject.toml
Builds Docker image
Pushes to DockerHub as:
- username/arctyk:latest
- username/arctyk:0.6.0 (version tag)
SSH to your Droplet at $DROPLET_HOST

Runs on server:

cd /srv/arctyk-itsm
git pull origin main
docker compose pull
 docker compose up -d
 # If templates/static look stale, restart web service
 docker compose restart web
docker system prune -f

Your App Restarts with new code

Common Issues & Fixes¶

Issue: "Push doesn't trigger deployment"¶

Cause: Branch tracking wrong remote Fix:

git branch --set-upstream-to=origin/main main

Issue: "Changes not showing on server"¶

Cause: Multiple possible reasons Debug:

# 1. Check if push succeeded
git status  # Should say "up to date with origin/main"

# 2. Check GitHub Actions
# Visit: https://github.com/your-username/arctyk-itsm/actions
# Look for green checkmark or red X

# 3. SSH to server and check
ssh -i ~/.ssh/github-actions-arctyk root@YOUR_DROPLET_IP
cd /srv/arctyk-itsm
git log -1  # Check latest commit
docker compose logs web  # Check container logs

# Refresh containers if code is behind or web didn't restart
git pull origin main
docker compose pull
docker compose up -d
docker compose restart web

Issue: "Tests fail on GitHub but pass locally"¶

Common causes:

Database state differences (migrations)
Missing environment variables
Test uses hardcoded paths
Race conditions in async tests

Fix: Run tests exactly as GitHub does:

$env:PYTHONPATH = "src"
$env:DATABASE_URL = "postgres://arctyk:arctyk@localhost:5432/arctyk_test"
pytest --maxfail=1 --disable-warnings

Issue: "Forgot to commit some files"¶

# Stage the missing files
git add path/to/forgotten/file.py

# Amend the last commit (if not pushed yet)
git commit --amend --no-edit

# Force push (only if not shared with others)
git push origin main --force

# OR make a new commit (safer)
git commit -m "fix: add missing file"
git push origin main

Quick Reference¶

Verify Branch Tracking¶

git branch -vv
# Should show: * main [origin/main] ...

Check Remote Branches¶

git remote -v
git branch -r  # List remote branches

Pull Latest from Main¶

git pull origin main

View Recent Commits¶

git log --oneline -10

Check What Changed¶

git diff  # Unstaged changes
git diff --staged  # Staged changes
git diff origin/main  # Compare with remote

Workflow Best Practices¶

Always check status before committing

git status

Pull before you push (if working with team)

git pull origin main
git push origin main

Use meaningful commit messages
feat: add user history timeline
fix: resolve null reference in changelog
chore: update dependencies
Check GitHub Actions after every push
Ensure tests pass
Confirm deployment succeeds
Check server logs if issues arise
Test locally before pushing
```
pytest
```

Emergency Rollback¶

If deployment breaks production:

Option 1: Revert Last Commit¶

git revert HEAD
git push origin main
# Triggers new deployment with changes reverted

Option 2: Rollback on Server¶

ssh -i ~/.ssh/github-actions-arctyk root@YOUR_DROPLET_IP
cd /srv/arctyk-itsm
git log --oneline -5  # Find good commit
git checkout abc1234  # Replace with good commit hash
docker compose up -d --build

Option 3: Use Previous Docker Tag¶

ssh -i ~/.ssh/github-actions-arctyk root@YOUR_DROPLET_IP
cd /srv/arctyk-itsm
# Edit docker-compose.yml to use specific version tag
# Change: image: username/arctyk:latest
# To: image: username/arctyk:0.5.0
docker compose up -d

Monitoring Deployment¶

Check GitHub Actions Status¶

# Use GitHub CLI (if installed)
gh run list --limit 5

# Or visit in browser
start https://github.com/your-username/arctyk-itsm/actions

Check Server Status¶

ssh -i ~/.ssh/github-actions-arctyk root@YOUR_DROPLET_IP "cd /srv/arctyk-itsm && docker compose ps"

View Live Logs¶

ssh -i ~/.ssh/github-actions-arctyk root@YOUR_DROPLET_IP
cd /srv/arctyk-itsm
docker compose logs -f web
# Ctrl+C to exit

Next Steps¶

Now that tracking is fixed, your workflow is:

Make changes locally
git add . (or specific files)
git commit -m "type: message"
git push origin main
Watch GitHub Actions at https://github.com/your-username/arctyk-itsm/actions
Wait ~5 minutes for deployment
Check your Droplet: Your changes are live!