GitHub Repository Setup

GitHub Repository Setup

For Claude: This skill sets up a GitHub repository with GitFlow branching, branch protection, issue/PR templates, and label-triggered CI.

When to Use

• Setting up a new GitHub repository with best practices
• Adding GitFlow branching to an existing repo
• Configuring branch protection rules
• Adding issue/PR templates and CI workflows

Flow

1. Check gh auth → login if needed
2. Ask: Create new or configure existing repo?
3. If new: Create repo with gh repo create
4. Setup GitFlow branches (main, develop)
5. Configure branch protection (owner can bypass)
6. Configure squash merge only + auto-delete branches
7. Add issue/PR templates
8. Add label-triggered CI workflow
9. Add Dependabot config for github-actions
10. Create .claude/.agents and CLAUDE.md/AGENTS.md symlinks
11. Display summary

Phase 1: Authentication

Check gh auth status:

gh auth status

If not authenticated, run:

gh auth login

Wait for user to complete authentication before proceeding.

Phase 2: Repo Selection

Parse arguments first:

• If --existing flag is present: Skip to "If Configure Existing" section
• If repo name is provided as argument: Use it (don't prompt for name)
• Otherwise: Ask user for mode

Ask user using AskUserQuestion (only if no --existing flag):

Header	Question	Options
"Repo mode"	"Create new repo or configure existing?"	"Create new repo", "Configure existing repo"

If Create New Repo:

Ask for details:

Header	Question	Options
"Visibility"	"Should the repo be public or private?"	"public", "private"

Get repo name from arguments or ask:

If no repo name in arguments, ask user to provide one.

Create repo (with initial README to enable branch operations):

# Use --public or --private based on user selection (lowercase)
# Include --add-readme to create initial commit (required for branch protection)
gh repo create <repo-name> --public --clone --add-readme
# OR
gh repo create <repo-name> --private --clone --add-readme
cd <repo-name>

If Configure Existing:

Verify current directory is a git repo with GitHub remote:

gh repo view --json nameWithOwner -q .nameWithOwner

If not a GitHub repo, inform user and exit.

Phase 3: GitFlow Branch Setup

Get current branch and repo info:

git branch --show-current
gh repo view --json defaultBranchRef -q .defaultBranchRef.name

Ensure main branch exists:

If default branch is not main (e.g., master), rename it:

# Get current default branch name
DEFAULT_BRANCH=$(gh repo view --json defaultBranchRef -q .defaultBranchRef.name)

# If not main, checkout default branch first then rename to main
if [ "$DEFAULT_BRANCH" != "main" ]; then
  git checkout "$DEFAULT_BRANCH"
  git branch -M main
  git push -u origin main
  # Update default branch on GitHub
  gh repo edit --default-branch main
fi

Create develop branch (skip if exists locally or remotely):

# Check if develop branch exists locally or on remote
if git show-ref --verify --quiet refs/heads/develop; then
  echo "develop branch already exists locally, skipping creation"
elif git ls-remote --heads origin develop | grep -q develop; then
  echo "develop branch exists on remote, fetching..."
  git fetch origin develop:develop
else
  git checkout -b develop
  git push -u origin develop
fi
git checkout main

Phase 4: Branch Protection

Get repo owner/name:

REPO=$(gh repo view --json nameWithOwner -q .nameWithOwner)

Create ci label for triggering CI:

gh label create ci --description "Trigger CI workflow" --color 0E8A16 || true

Protect main branch:

Note: Status checks are initially set to null because the exact check context (e.g., "CI / ci") is only known after the first workflow run. After the first CI run, update protection to require that specific check.

gh api repos/$REPO/branches/main/protection \
  -X PUT \
  -H "Accept: application/vnd.github+json" \
  --input - << 'EOF'
{
  "required_pull_request_reviews": {
    "required_approving_review_count": 1,
    "dismiss_stale_reviews": true
  },
  "required_status_checks": null,
  "enforce_admins": false,
  "restrictions": null,
  "allow_force_pushes": false,
  "allow_deletions": false
}
EOF

Protect develop branch:

gh api repos/$REPO/branches/develop/protection \
  -X PUT \
  -H "Accept: application/vnd.github+json" \
  --input - << 'EOF'
{
  "required_pull_request_reviews": null,
  "required_status_checks": null,
  "enforce_admins": false,
  "restrictions": null,
  "allow_force_pushes": false,
  "allow_deletions": false
}
EOF

Configure squash merge only:

gh api repos/$REPO \
  -X PATCH \
  -H "Accept: application/vnd.github+json" \
  -F allow_squash_merge=true \
  -F allow_merge_commit=false \
  -F allow_rebase_merge=false \
  -F delete_branch_on_merge=true

Note: enforce_admins: false allows repo owner/admins to bypass protection. After first CI run, update protection to require the status check using:

# Get exact check name from a completed PR, then update protection
gh api repos/$REPO/branches/main/protection/required_status_checks \
  -X PATCH --input - << 'EOF'
{
  "strict": true,
  "checks": [{"context": "CI / ci"}]
}
EOF

Phase 5: Templates

Check for uncommitted changes before proceeding:

if [ -n "$(git status --porcelain)" ]; then
  echo "Warning: Uncommitted changes detected"
fi

If uncommitted changes exist, use AskUserQuestion:

Header	Question	Options
"Changes"	"You have uncommitted changes. Continue with setup?"	"Continue", "Abort"

If user aborts, exit the skill.

Create .github directory structure:

mkdir -p .github/ISSUE_TEMPLATE .github/workflows

Check for existing template files before creating:

# Check if any template files exist
EXISTING_FILES=""
[ -f .github/ISSUE_TEMPLATE/bug_report.md ] && EXISTING_FILES="$EXISTING_FILES bug_report.md"
[ -f .github/ISSUE_TEMPLATE/feature_request.md ] && EXISTING_FILES="$EXISTING_FILES feature_request.md"
[ -f .github/PULL_REQUEST_TEMPLATE.md ] && EXISTING_FILES="$EXISTING_FILES PULL_REQUEST_TEMPLATE.md"
[ -f .github/workflows/ci.yml ] && EXISTING_FILES="$EXISTING_FILES ci.yml"

If any files exist, use AskUserQuestion:

Header	Question	Options
"Existing"	"These files exist: {files}. Overwrite?"	"Overwrite all", "Skip existing"

Based on user choice:

• Overwrite all: Create all template files (overwriting existing)
• Skip existing: Only create files that don't exist yet

For each file below, check if it should be created based on user choice:

Create bug report template at .github/ISSUE_TEMPLATE/bug_report.md (if not skipping):

---
name: Bug Report
about: Report a bug to help us improve
labels: bug
---

## Description

A clear description of the bug.

## Steps to Reproduce

1.
2.
3.

## Expected Behavior

What should happen.

## Actual Behavior

What actually happens.

## Environment

- OS:
- Version:

Create feature request template at .github/ISSUE_TEMPLATE/feature_request.md:

---
name: Feature Request
about: Suggest a new feature
labels: enhancement
---

## Problem

What problem does this solve?

## Proposed Solution

How should it work?

## Alternatives Considered

Other approaches you've thought about.

Create PR template at .github/PULL_REQUEST_TEMPLATE.md:

## Summary

Brief description of changes.

## Type of Change

- [ ] Bug fix
- [ ] New feature
- [ ] Breaking change
- [ ] Documentation

## Checklist

- [ ] Tests pass locally
- [ ] Code follows project style
- [ ] Documentation updated (if needed)

Phase 6: CI Workflow

Create CI workflow at .github/workflows/ci.yml:

name: CI

on:
  pull_request:
    types: [labeled, synchronize]
    branches: [main, develop]

jobs:
  ci:
    if: contains(github.event.pull_request.labels.*.name, 'ci')
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Setup (customize for your project)
        run: echo "Add setup steps here"

      - name: Lint
        run: echo "Add lint command here"

      - name: Test
        run: echo "Add test command here"

Note: CI only runs when PR has the ci label.

Create Dependabot config at .github/dependabot.yml:

version: 2
updates:
  - package-ecosystem: "github-actions"
    directory: "/"
    schedule:
      interval: "weekly"
    commit-message:
      prefix: "chore(deps)"

Note: Dependabot will automatically create PRs for outdated GitHub Actions.

Create project structure symlinks:

# Create .agents directory if it doesn't exist
mkdir -p .agents

# Create symlink .claude -> .agents (for Claude Code compatibility)
[ -L .claude ] || [ -d .claude ] || ln -s .agents .claude

# Create AGENTS.md if it doesn't exist (placeholder)
[ -f AGENTS.md ] || echo "# Agent Instructions\n\nProject-specific instructions for AI agents." > AGENTS.md

# Create symlink CLAUDE.md -> AGENTS.md
[ -L CLAUDE.md ] || [ -f CLAUDE.md ] || ln -s AGENTS.md CLAUDE.md

Note: These symlinks ensure compatibility with both Claude Code (which reads CLAUDE.md and .claude/) and other AI agents (which may use AGENTS.md and .agents/).

Phase 7: Commit and Summary

Stage and commit all template files (only if changes exist):

git add .github/ .agents/ .claude AGENTS.md CLAUDE.md
# Only commit if there are staged changes
git diff --staged --quiet || git commit -m "chore: add GitHub templates, CI workflow, and project structure

- Bug report and feature request issue templates
- Pull request template
- Label-triggered CI workflow
- Dependabot config for github-actions
- .agents/.claude directories and AGENTS.md/CLAUDE.md symlinks

Co-Authored-By: Claude <[email protected]>"

Push changes (only if there were commits):

# Push to origin, setting upstream if needed
git push -u origin HEAD

Display summary:

GitHub Repository Setup Complete

Repository: {repo-name}

Branches:
  ✓ main (protected: 1 review required)
  ✓ develop (protected)
  Note: Admins can bypass protection rules

Merge Settings:
  ✓ Squash merge only (merge commit and rebase disabled)
  ✓ Auto-delete branches after merge

Templates Added:
  ✓ .github/ISSUE_TEMPLATE/bug_report.md
  ✓ .github/ISSUE_TEMPLATE/feature_request.md
  ✓ .github/PULL_REQUEST_TEMPLATE.md

CI & Automation:
  ✓ .github/workflows/ci.yml (triggers on 'ci' label)
  ✓ .github/dependabot.yml (weekly updates for github-actions)

Project Structure:
  ✓ .agents/ directory (with .claude symlink)
  ✓ AGENTS.md (with CLAUDE.md symlink)

Next Steps:
  1. Customize .github/workflows/ci.yml for your project
  2. Create first feature branch: git checkout -b feature/my-feature develop
  3. Add 'ci' label to a PR to trigger first CI run
  4. After first CI run, update branch protection to require status checks

Error Handling

Error	Action
Not authenticated	Run gh auth login and wait
Repo already exists	Ask user: configure existing repo or abort
Repo creation fails	Display error, suggest checking name/permissions
Branch protection fails	Check if user has admin access to repo
Not a git repo	Inform user, exit skill
develop branch exists	Skip creation, continue
Template files exist	Ask user: overwrite or skip