repo-setup

Fork, clone, and set up a GitHub repository for development or contribution. Handles fork creation, clone with authentication, upstream remote configuration, branch creation from upstream, and dependency installation. Use when starting work on a new open-source project, setting up a multi-repo development environment, or onboarding to a new codebase.

Repo Setup — Fork, Clone & Branch Setup

Overview

Automate the setup of a local development environment for contributing to or working on GitHub repositories. Handles the full fork → clone → branch → dependencies pipeline.

Use cases: Open-source contribution, multi-repo development, new project onboarding, codebase exploration.

Prerequisites

gh auth status   # Must show "Logged in"
git --version    # Git installed

If not configured, ask the user to provide:

1. GitHub username — used for fork URLs and clone paths
2. GitHub token — run gh auth login or set export GH_TOKEN=<token>

Token is required for: forking repos, cloning private forks, pushing code. Without it, git push and gh repo fork will fail.

Workflow

Step 1: Get Parameters

Parameter	Required	Default	Example
Repository	✅	—	owner/repo
GitHub username	✅	—	myusername
Branch name	❌	(stay on default)	fix/bug-description
Working directory	❌	~/prs/{repo}	~/dev/{repo}
Auth method	❌	GH_TOKEN env var	Token in URL, SSH

Step 2: Fork

gh repo fork {owner}/{repo} --clone=false

If fork already exists, this is a no-op. If the user already owns the repo, skip forking.

Step 3: Clone

WORKDIR="${WORK_BASE:-$HOME/prs}/{repo_name}"

if [ -d "$WORKDIR" ]; then
    cd "$WORKDIR"
    git fetch --all
else
    mkdir -p "$(dirname "$WORKDIR")"

    # With token auth
    git clone "https://${GH_TOKEN}@github.com/${username}/${repo_name}.git" "$WORKDIR"

    # Or with SSH
    # git clone "[e-mail]:${username}/${repo_name}.git" "$WORKDIR"

    cd "$WORKDIR"
fi

Step 4: Configure Upstream Remote

if ! git remote get-url upstream &>/dev/null; then
    git remote add upstream "https://github.com/${owner}/${repo_name}.git"
fi
git fetch upstream

Step 5: Create Feature Branch

# Detect default branch
DEFAULT_BRANCH=$(git remote show upstream 2>/dev/null | grep 'HEAD branch' | awk '{print $NF}')
DEFAULT_BRANCH="${DEFAULT_BRANCH:-main}"

# Create branch from latest upstream
git checkout -b {branch_name} upstream/$DEFAULT_BRANCH

Branch Naming Conventions

Type	Pattern	Example
Bug fix	fix/{short-description}	fix/null-pointer-on-empty-list
Feature	feat/{short-description}	feat/add-retry-logic
Refactor	refactor/{short-description}	refactor/extract-auth-module
Review iteration	fix/{description}-v2	fix/tool-guards-v2

Step 6: Install Dependencies

Detect the project type and install accordingly:

Indicator	Language	Install Command
pyproject.toml / setup.py	Python	pip install -e ".[dev]" or pip install -e .
requirements.txt	Python	pip install -r requirements.txt
package.json	Node.js	npm install
go.mod	Go	go mod download
Cargo.toml	Rust	cargo build
pom.xml	Java	mvn install -DskipTests
build.gradle	Java/Kotlin	./gradlew build -x test

If full dev install fails (common with native dependencies):

1. Install core deps individually
2. Skip optional native/GPU deps
3. Ensure test framework is installed at minimum

Step 7: Verify

# Check setup
echo "Directory: $(pwd)"
echo "Branch: $(git branch --show-current)"
echo "Upstream: $(git remote get-url upstream)"
echo "Fork: $(git remote get-url origin)"

# Quick build/import test
# Python: python -c "import {package}"
# Node: npm run build (if applicable)
# Go: go build ./...

Automation Script

A helper script is available if this Skill is installed alongside oss-pr-campaign:

# One-liner setup
scripts/setup_repo.sh owner/repo username fix/branch-name

Or implement the same logic step-by-step using the SOP above.

Output

• Local repo at ~/prs/{repo}/ (or custom directory) on feature branch
• Upstream remote configured
• Dependencies installed
• Ready for development

Tips

• When used as part of a development pipeline, this follows issue-hunter and feeds into dev-test.
• For exploring a codebase without contributing, skip the fork step and clone the original directly.
• Store GH_TOKEN in your shell profile for persistent auth across sessions.
• If working on multiple repos, keep them all under ~/prs/ for easy navigation.