Github Team Workflow

Initialization & Authentication

# Start interactive authentication if not logged in
gh auth login

# Protocol:
# 1. Select GitHub.com
# 2. Select SSH (preferred) or HTTPS
# 3. Select "Login with a web browser"

Zsh Integration (Optional)

Add to ~/.zshrc:

if type gh &>/dev/null; then
    eval "$(gh completion -s zsh)"
fi

Reload:

source ~/.zshrc

Branch and PR Strategy

⚠️ IMPORTANT: All PRs target main by default.

Only create a PR targeting staging if the user explicitly says they want to target staging (e.g., "create a PR to staging", "merge this to staging first", "I want this in staging").

Branch Prefixes

Both branch types target main unless the user explicitly requests staging.

Core Workflow: Creating a Branch and PR

Use this workflow for all changes. PRs always go to main unless explicitly told otherwise.

# 1. Fetch latest and checkout main
git fetch origin main
git checkout main
git pull origin main

# 2. Create branch (feature/ for new work, fix/ for bug fixes)
git checkout -b feature/{descriptive-name}
# OR
git checkout -b fix/{component}-{brief-description}

# 3. Make changes, commit, and push
git add <files>
git commit -m "Brief description of change"
git push -u origin feature/{descriptive-name}

# 4. Create PR targeting MAIN (default)
gh pr create --base main --title "Add feature" --body "Description"

Branch Naming Examples

Only When User Explicitly Requests Staging

If (and only if) the user explicitly says they want to target staging:

# Create PR targeting STAGING (only when explicitly requested)
gh pr create --base staging --title "Add feature" --body "Description"

Trigger phrases that indicate staging:

• "create a PR to staging"
• "merge to staging"
• "target staging"
• "I want this in staging first"
• "staging branch"

If none of these phrases appear, always use main.

Fix Branch Workflow (Bug Fixes)

For bug fixes and urgent production issues:

# 1. If you have uncommitted changes you want to preserve, save them
git diff path/to/file > /tmp/fix.patch

# 2. Discard local changes and checkout fresh main
git checkout .
git fetch origin main
git checkout main
git pull origin main

# 3. Create fix branch from main
git checkout -b fix/{dag-or-component-name}-{brief-description}

# 4. Apply fix (either manually or from patch)
git apply /tmp/fix.patch  # if using patch
# OR make changes directly

# 5. Commit and push
git add <files>
git commit -m "Fix: brief description of the fix"
git push -u origin fix/{branch-name}

# 6. Create PR targeting MAIN
gh pr create --base main --title "Fix: description" --body "## Summary
- What was broken
- What was fixed

## Test plan
- [x] Verified fix locally"

Quick Reference: Branch Type Selection

Creating a Branch from GitHub Issue

If working from a GitHub issue, include the issue number:

# Get issue title and slugify
ISSUE_NUM=690
ISSUE_TITLE=$(gh issue view $ISSUE_NUM --json title --jq '.title')
SLUG=$(echo "$ISSUE_TITLE" | tr '[:upper:]' '[:lower:]' | sed 's/[^a-z0-9 -]//g' | tr ' ' '-' | sed 's/-\+/-/g' | sed 's/^-\|-$//g')
BRANCH_NAME="feature/${SLUG}-${ISSUE_NUM}"
git checkout -b $BRANCH_NAME

Example: Issue "LSA automation improvements #690" → Branch: feature/lsa-automation-improvements-690

See BRANCH_NAMING.md for slugification rules and edge cases.

Committing Changes

Only commit files modified during this Claude Code session. Never include unrelated changes.

# 1. Review what changed
git status
git diff

# 2. Stage ONLY files you modified (explicit paths, never `git add .`)
git add path/to/file1.py path/to/file2.sql

# 3. Verify staged changes are yours
git diff --cached --stat

# 4. Commit with brief message
git commit -m "Brief description of change"

Commit message guidelines:

• Keep under 72 characters
• Describe what changed, not why (the PR describes why)
• No need for conventional commit prefixes unless CLAUDE.md specifies otherwise

Pushing and Creating PRs

Before pushing, verify no foreign commits are included.

# 1. Get your GitHub username
GH_USER=$(gh api user --jq '.login')

# 2. Check commits on this branch not on default branch
DEFAULT_BRANCH=$(gh repo view --json defaultBranchRef --jq '.defaultBranchRef.name')
git log origin/$DEFAULT_BRANCH..HEAD --format="%an" | sort -u

# 3. If ALL commits show your username (or mapped git name), proceed
git push -u origin HEAD

If foreign commits are detected: Do NOT push. Inform the user that the branch contains commits from other authors and ask how to proceed (likely need to reset and cherry-pick).

Creating a Pull Request

# 1. Read workflow triggers to understand what CI runs
cat .github/workflows/*.yml | grep -A 5 "on:" | head -40

# 2. Create PR to MAIN (default - always use main unless user explicitly requests staging)
gh pr create --base main --fill

# Or with explicit title/body:
gh pr create --base main --title "Brief title" --body "Description of changes"

After PR creation:

1. Note the PR number/URL for the user
2. Check if any Actions started: gh run list --limit 5
3. If Actions are running, wait and monitor (see Troubleshooting below)

Repository-Specific Merge Rules

Each repo has different CI checks and merge permissions. Always identify which repo you're in before deciding the post-PR workflow.

data-dbt: Code Owner Approval + Self-Merge

data-dbt has a claude-config-protection ruleset on main that requires code owner review from aptive-env/data. No CI checks run, so after approval the PR can be merged immediately.

# 1. Create PR
gh pr create --base main --title "feat: description" --body "..."

# 2. Wait for code owner approval (notify user to request approval)
gh pr view <PR-NUMBER> --json reviews --jq '.reviews[] | {author: .author.login, state: .state}'

# 3. After approval, merge
gh pr merge <PR-NUMBER> --merge --delete-branch

If the approver merges via the GitHub UI, the PR will already be merged. Check first:

gh pr view <PR-NUMBER> --json state --jq '.state'

data-airflow, data-de-martech, data-de-coms: Monitor CI + Stop at PR

These repos have CI checks that must pass. After creating the PR, monitor checks and fix any failures. Do NOT merge — a human reviewer will handle that.

# 1. Create PR
gh pr create --base main --title "feat: description" --body "..."

# 2. Monitor CI checks (poll until complete)
gh pr checks <PR-NUMBER> --watch

# 3. If checks fail, get details
gh run list --limit 5
gh run view <RUN_ID> --log-failed

# 4. Fix failures, push, re-check
git add <fixed-files> && git commit -m "fix: CI failure" && git push
gh pr checks <PR-NUMBER> --watch

# 5. Stop here — human review required for merge

PR Operations with gh

# Checkout & switch to a PR branch
gh pr checkout <PR-NUMBER>

# Check PR status and CI
gh pr checks <PR-NUMBER>

# Watch CI checks until they complete
gh pr checks <PR-NUMBER> --watch

# View PR review status
gh pr view <PR-NUMBER> --json reviews --jq '.reviews[] | {author: .author.login, state: .state}'

# Merge (only for data-dbt after approval)
gh pr merge <PR-NUMBER> --merge --delete-branch

Repo Management (gh)

# Fork and clone
gh repo fork <org>/<repo> --clone

# Sync fork with upstream
gh repo sync

data-airflow Mandatory PR Requirements (Non-Negotiable)

These requirements are mandatory for /home/aptive/airflow/data-airflow. Do not open or merge PRs until they are met.

• Flake8 (Required):

  pip install flake8
  flake8
  

  GitHub Actions runs flake8 and will reject PRs with lint errors.

• Mypy (Required):

  pip install mypy
  mypy <paths-you-touched>
  

  Run mypy on the files you changed (e.g., dags/, scripts/, common/). This is mandatory even if CI does not run it yet.

• Secrets Scan (Required):

  pip install detect-secrets
  detect-secrets scan > detect-secrets-output.json
  

  CI runs detect-secrets (uses .secrets.baseline if present) and will fail PRs if new secrets are detected.

• Branching Rules (Required):

  • Create feature branches from main for standard work.
  • Create feature branches from staging only for extended testing needs.
  • PRs target main or staging only.
  • staging auto-resets to main every Wednesday at 5AM UTC.
  • Cherry-pick staging-tested commits onto a main-based branch before merging to main.

PR Follow-Through TODO (Mandatory)

Creating a PR is not the finish line. Follow the repo-specific workflow (see "Repository-Specific Merge Rules" above).

For repos with CI checks (data-airflow, data-de-martech, data-de-coms):

1. Create the PR with the correct base branch (main or staging).
2. Monitor checks: gh pr checks <PR-NUMBER> --watch
3. If any checks fail (flake8, detect-secrets, terraform fmt, etc.), fix issues and push updates.
4. Re-run gh pr checks --watch after each push.
5. Once all checks are green, stop — a human reviewer will merge.

For data-dbt (no CI checks):

1. Create the PR targeting main.
2. Notify user that code owner approval is required from aptive-env/data.
3. After approval, merge: gh pr merge <PR-NUMBER> --merge --delete-branch
4. If the approver already merged via GitHub UI, confirm with gh pr view <PR-NUMBER> --json state.

Updating a Branch with Latest Main

When the PR is behind the default branch:

git fetch origin
git rebase origin/main

# If conflicts occur, resolve them, then:
git rebase --continue

# Force push (safe for feature branches)
git push --force-with-lease

Advanced Local Workflows (git)

Interactive Rebase (History Cleaning)

# Interactive mode on last N commits
git rebase -i HEAD~5
# OR rebase onto main
git rebase -i $(git merge-base HEAD main)

# Operations:
# p, pick = use commit
# r, reword = use commit, edit message
# s, squash = use commit, meld into previous
# d, drop = remove commit

git push --force-with-lease

Parallel Development (Worktrees)

# Create a parallel worktree
git worktree add ../hotfix-branch hotfix/critical-bug

# Remove worktree when complete
git worktree remove ../hotfix-branch
git worktree prune

Cherry-Picking (Tactical Deployment)

# Apply single commit
git cherry-pick <COMMIT-HASH>

# Apply range (A exclusive, B inclusive)
git cherry-pick <HASH-A>..<HASH-B>

# Conflict resolution
git cherry-pick --continue
# OR
git cherry-pick --abort

Bisect (Bug Hunting)

git bisect start
git bisect bad HEAD
git bisect good v1.0.0

# Mark each tested revision as bad or good
git bisect bad
git bisect good

git bisect reset

GitHub Actions Awareness

Understanding What Runs

Before creating a PR, understand what CI/CD will trigger:

# List all workflows
gh workflow list

# View specific workflow triggers
cat .github/workflows/{workflow-name}.yml | grep -A 10 "on:"

Common triggers to know:

• on: pull_request - Runs on PR creation/update
• on: push: branches: [main] - Runs after merge to main
• on: workflow_dispatch - Manual trigger only

When Actions Fail

See TROUBLESHOOTING.md for diagnosis steps.

Key principle: The workflows themselves are correct. If Actions fail, it's due to:

1. Code issues (fix the code, push again)
2. Environment/infrastructure issues (escalate to user)

Never edit files in .github/ - this folder is read-only.

Pre-Push Checklist

Before every push, verify:

• Branch is rebased on latest main
• Only files you modified are staged
• No commits from other users in your branch
• Commit messages are brief and clear
• You understand what Actions will run
• PR will target main (unless user explicitly requested staging)

Recovery Protocols (Reflog)

# View the reflog
git reflog

# Recover a lost commit
git checkout <LOST-HASH>
git branch recovered-branch

# Reset hard to a point in time
git reset --hard HEAD@{10.minutes.ago}

Recommended Aliases

Add to ~/.zshrc for speed:

# GH Aliases
alias gprc='gh pr create'
alias gprm='gh pr merge -s -d'
alias gprv='gh pr view --web'
alias gco='gh pr checkout'

# Git Advanced Aliases
alias grb='git rebase -i'
alias gcp='git cherry-pick'
alias gwta='git worktree add'
alias gl='git log --graph --oneline --decorate'
alias gfl='git push --force-with-lease'

Escalation

Raise to the user for boss escalation when:

• GitHub Actions fail due to workflow configuration issues (not code)
• Secret/environment variable issues
• Permission/access problems
• Infrastructure failures (runners, external services)

Provide specific error messages and your diagnosis when escalating.

TROUBLESHOOTING.md

Reference this when GitHub Actions fail after a push or PR.

Diagnosis Workflow

Step 1: Get Failure Details

# List recent workflow runs
gh run list --limit 10

# Get details of failed run (replace RUN_ID)
gh run view RUN_ID

# Get full logs
gh run view RUN_ID --log-failed

Step 2: Categorize the Failure

Step 3: For Code Issues - Fix and Retry

# 1. Identify the failing file(s) from logs
gh run view RUN_ID --log-failed | grep -E "(Error|FAILED|error:)" 

# 2. Fix the code

# 3. Commit and push
git add <fixed-files>
git commit -m "Fix: <brief description of fix>"
git push

Step 4: For Non-Code Issues - Escalate

Provide the user with:

1. Run ID and link: gh run view RUN_ID --web (or provide URL)
2. Error category: Workflow config / Infrastructure / Permissions
3. Specific error message: Copy the relevant log lines
4. Your assessment: Why this cannot be fixed by code changes

Example escalation message:

GitHub Actions failed due to a workflow configuration issue.

- Run: https://github.com/org/repo/actions/runs/123456
- Error: Secret `DEPLOY_KEY` is not set
- Assessment: This requires adding a repository secret, which is outside my scope.

Please escalate to your team lead to resolve the secret configuration.

Step 4: Use the task-complete-notify skill to inform the user the GIT tasks are complete, whether the issue was resolved or escalated.

Common Failure Patterns

Python/Data Engineering Specific

Re-running Failed Jobs

# Rerun only failed jobs (faster)
gh run rerun RUN_ID --failed

# Rerun entire workflow
gh run rerun RUN_ID

Only rerun without code changes if you suspect a flaky test or transient infrastructure issue. If it fails twice the same way, it's not flaky.

BRANCH_NAMING.md

Format

feature/{slugified-description}
feature/{slugified-issue-title}-{issue-number}
fix/{component}-{brief-description}

Slugification Rules

1. Convert to lowercase
2. Replace spaces with hyphens
3. Remove special characters except hyphens
4. Collapse multiple hyphens into one
5. Trim hyphens from start/end
6. Append issue number at end (if from an issue)

Examples

Generating from GitHub Issue

# Get issue title and number, then slugify
ISSUE_NUM=690
ISSUE_TITLE=$(gh issue view $ISSUE_NUM --json title --jq '.title')
SLUG=$(echo "$ISSUE_TITLE" | tr '[:upper:]' '[:lower:]' | sed 's/[^a-z0-9 -]//g' | tr ' ' '-' | sed 's/-\+/-/g' | sed 's/^-\|-$//g')
BRANCH_NAME="feature/${SLUG}-${ISSUE_NUM}"
echo $BRANCH_NAME

Edge Cases

Very long titles: If the branch name exceeds 100 characters, truncate the slug portion (keep the issue number):

# Truncate slug to keep total under 100 chars
MAX_SLUG_LEN=$((100 - ${#ISSUE_NUM} - 9))  # 9 = "feature/-" + "-"
SLUG="${SLUG:0:$MAX_SLUG_LEN}"

No associated issue: If working without an issue, use a descriptive slug without a number:

feature/descriptive-task-name

But prefer creating an issue first for traceability.

Testing Suggestions

Test with these prompts to verify the skill triggers correctly:

Should Trigger ✅

1. "Create a new branch for issue #690"
2. "I've made changes to the ETL script, help me commit and push"
3. "Create a PR for my changes"
4. "The GitHub Action failed, can you check what went wrong?"
5. "My branch is behind main, help me update it"
6. "Push my changes to GitHub"
7. "Create a fix branch for this DAG bug"
8. "This DAG is broken in production, create a fix branch"
9. "Create a PR to staging for this feature" ← Only this should target staging

Should NOT Trigger ❌

1. "Explain how git rebase works" (general git knowledge, not team workflow)
2. "Help me write a GitHub Action" (out of scope - .github is read-only)
3. "Set up a new GitHub repository" (admin task, out of scope)

Real-World Examples

Example: Fix Branch Workflow (PR #734)

Scenario: DAG plan_builder_nightly was failing with 401 errors.

Steps taken:

# 1. Save the fix as a patch (had uncommitted changes on another branch)
git diff dags/plan_builder_nightly/src/api_client.py > /tmp/api_client_fix.patch

# 2. Discard local changes, checkout main
git checkout .
git fetch origin main
git checkout main
git pull origin main

# 3. Create fix branch
git checkout -b fix/plan-builder-nightly-api-token

# 4. Apply the patch
git apply /tmp/api_client_fix.patch

# 5. Commit and push
git add dags/plan_builder_nightly/src/api_client.py
git commit -m "Fix plan_builder_nightly API token retrieval"
git push -u origin fix/plan-builder-nightly-api-token

# 6. Create PR to main
gh pr create --base main --title "Fix plan_builder_nightly API token retrieval" --body "..."

Result: PR #734 created targeting main, CI passed, ready for review.

Example: Feature Branch Workflow (PR #730)

Scenario: New DAG needed for Twilio data integration.

Steps taken:

# 1. Checkout main
git checkout main
git pull origin main

# 2. Create feature branch
git checkout -b feature/twilio-genesys-to-snowflake

# 3. Develop the feature, commit
git add dags/twilio_genesys_to_snowflake/
git commit -m "Add twilio_genesys_to_snowflake DAG"
git push -u origin feature/twilio-genesys-to-snowflake

# 4. Create PR to main (default)
gh pr create --base main --title "Add twilio_genesys_to_snowflake DAG" --body "..."

Result: PR #730 created targeting main.