Git-Steer Setup Guide: From Zero to Steering in 10 Minutes

Overview

This guide walks you through setting up git-steer from scratch. By the end, you’ll have:

• A GitHub App with the right permissions
• Credentials securely stored in macOS Keychain
• A private state repository for configuration and audit logs
• Claude Desktop configured to use git-steer

Prerequisites:

• macOS (for Keychain integration)
• Node.js 18+
• GitHub account
• Claude Desktop installed

---

Git-Steer Series:

1. Introduction - Architecture and philosophy
2. Setup Guide (this post) - Step-by-step installation
3. Advanced Patterns - Custom workflows and extensions

---

Step 1: Create a GitHub App

GitHub Apps provide secure, scoped access to your repositories without using personal access tokens.

1.1 Navigate to GitHub App Settings

Go to: https://github.com/settings/apps/new

Or: GitHub → Settings → Developer Settings → GitHub Apps → New GitHub App

1.2 Fill in App Details

Field	Value
GitHub App name	git-steer (must be unique)
Homepage URL	https://github.com/YOUR-USERNAME/git-steer
Webhook	Uncheck “Active” (not needed)

1.3 Set Permissions

Under Repository permissions:

Permission	Access Level
Contents	Read and write
Metadata	Read-only
Pull requests	Read and write
Actions	Read and write
Administration	Read and write
Dependabot alerts	Read-only
Secrets	Read and write

Under Account permissions:

• None required

1.4 Create and Note the App ID

After creating the app, you’ll see an App ID at the top of the page. Save this number.

Example: App ID: 2772677

1.5 Generate a Private Key

Scroll down to Private keys and click Generate a private key.

A .pem file will download. Keep this safe—it’s your authentication credential.

---

Step 2: Install the App

2.1 Install to Your Account

On the app page, click Install App in the left sidebar.

Select your account and choose:

• All repositories (recommended for full control)
• Or Only select repositories (if you want to limit scope)

2.2 Note the Installation ID

After installation, you’ll be redirected to a URL like:

https://github.com/settings/installations/107312000

The number at the end (107312000) is your Installation ID. Save this.

---

Step 3: Store Credentials in Keychain

git-steer uses macOS Keychain for secure credential storage. No config files, no environment variables.

3.1 Store the App ID

security add-generic-password \
  -s "git-steer" \
  -a "git-steer-app-id" \
  -w "YOUR_APP_ID"

Replace YOUR_APP_ID with your actual App ID (e.g., 2772677).

3.2 Store the Installation ID

security add-generic-password \
  -s "git-steer" \
  -a "git-steer-installation-id" \
  -w "YOUR_INSTALLATION_ID"

Replace YOUR_INSTALLATION_ID with your actual Installation ID.

3.3 Store the Private Key

The private key needs to be hex-encoded for Keychain storage:

cat ~/Downloads/your-app-name.*.private-key.pem | xxd -p | tr -d '\n' | \
  security add-generic-password \
  -s "git-steer" \
  -a "git-steer-private-key" \
  -w "$(cat -)"

3.4 Verify Storage

# Check all credentials exist
security find-generic-password -s "git-steer" -a "git-steer-app-id" -w
security find-generic-password -s "git-steer" -a "git-steer-installation-id" -w
security find-generic-password -s "git-steer" -a "git-steer-private-key" -w | head -c 50

You should see your App ID, Installation ID, and the beginning of the hex-encoded key.

---

Step 4: Create the State Repository

git-steer stores all configuration and audit logs in a private GitHub repository.

4.1 Create the Repository

gh repo create git-steer-state --private --description "git-steer configuration and state"

Or create it manually at https://github.com/new:

• Name: git-steer-state
• Visibility: Private

4.2 Initialize with Config Structure

# Clone the empty repo
git clone https://github.com/YOUR-USERNAME/git-steer-state
cd git-steer-state

# Create directory structure
mkdir -p config state .github/workflows

# Create initial config files
cat > config/managed-repos.yaml << 'EOF'
# Repositories managed by git-steer
repos:
  - owner: YOUR-USERNAME
    name: "*"  # All repos
    policies:
      - default-branch-protection
EOF

cat > config/policies.yaml << 'EOF'
# Branch protection policies
default-branch-protection:
  protection:
    required_reviews: 1
    dismiss_stale_reviews: true
    require_code_owner_reviews: false
EOF

cat > config/schedules.yaml << 'EOF'
# Scheduled jobs
jobs:
  security-scan:
    cron: "0 6 * * *"  # Daily at 6 AM UTC
    action: security_digest
    params:
      severity: high
EOF

# Initialize state files
echo '[]' > state/audit.jsonl
echo '[]' > state/jobs.jsonl
echo '{}' > state/cache.json

# Commit and push
git add .
git commit -m "Initialize git-steer state repository"
git push origin main

4.3 Store State Repo in Keychain

security add-generic-password \
  -s "git-steer" \
  -a "git-steer-state-repo" \
  -w "YOUR-USERNAME/git-steer-state"

---

Step 5: Configure Claude Desktop

5.1 Locate the Config File

Claude Desktop’s MCP configuration is at:

~/Library/Application Support/Claude/claude_desktop_config.json

5.2 Add git-steer

Edit the file to add git-steer as an MCP server:

{
  "mcpServers": {
    "git-steer": {
      "command": "npx",
      "args": ["git-steer"]
    }
  }
}

Alternative: Local Development

If you’ve cloned git-steer locally for development:

{
  "mcpServers": {
    "git-steer": {
      "command": "node",
      "args": ["/path/to/git-steer/bin/cli.js", "start", "--stdio"]
    }
  }
}

5.3 Restart Claude Desktop

Quit and reopen Claude Desktop for the changes to take effect.

---

Step 6: Set Up GitHub Actions Secrets

For git-steer’s workflows to authenticate to your repos, add secrets to the git-steer repository:

# Get credentials from Keychain
APP_ID=$(security find-generic-password -s "git-steer" -a "git-steer-app-id" -w)
PRIVATE_KEY=$(security find-generic-password -s "git-steer" -a "git-steer-private-key" -w | xxd -r -p)

# Set as GitHub secrets
echo "$APP_ID" | gh secret set GIT_STEER_APP_ID --repo YOUR-USERNAME/git-steer
echo "$PRIVATE_KEY" | gh secret set GIT_STEER_PRIVATE_KEY --repo YOUR-USERNAME/git-steer

This allows the security-fix.yml workflow to generate installation tokens for any repo.

---

Step 7: Verify Installation

7.1 Test in Claude Desktop

Open Claude Desktop and try:

“List all my GitHub repos”

You should see git-steer respond with a list of your repositories.

7.2 Test Security Scanning

“Scan my repos for security vulnerabilities”

git-steer will check Dependabot alerts across all accessible repositories.

7.3 Test Status

“Show git-steer status”

You should see:

• Authentication status
• Rate limit information
• State sync status
• Number of managed repos

---

Troubleshooting

”Not authenticated” Error

Cause: Credentials not found in Keychain or incorrect.

Fix:

# Verify credentials exist
security dump-keychain | grep git-steer

# Re-add if missing (see Step 3)

“Installation not found” Error

Cause: Installation ID is wrong or app not installed to account.

Fix:

1. Go to https://github.com/settings/installations
2. Find your git-steer installation
3. Verify the Installation ID in the URL
4. Update Keychain if needed

Claude Desktop Doesn’t Show git-steer

Cause: Config file syntax error or wrong location.

Fix:

# Check config file location
cat ~/Library/Application\ Support/Claude/claude_desktop_config.json

# Validate JSON syntax
cat ~/Library/Application\ Support/Claude/claude_desktop_config.json | jq .

Rate Limit Errors

Cause: Too many API calls in a short period.

Fix:

# Check rate limit status via Claude
# "Show git-steer status"

# Or directly via gh CLI
gh api rate_limit

GitHub Apps have a limit of 5,000 requests per hour per installation.

---

Security Considerations

Credential Rotation

To rotate the private key:

1. Generate a new key in GitHub App settings
2. Update Keychain:

   security delete-generic-password -s "git-steer" -a "git-steer-private-key"
   # Then re-add with new key (Step 3.3)

3. Update GitHub Actions secrets
4. Delete old key from GitHub App settings

Limiting Scope

If you don’t want git-steer to access all repos:

1. Go to https://github.com/settings/installations/YOUR_INSTALLATION_ID
2. Click Configure
3. Select Only select repositories
4. Choose specific repos

Audit Logs

All git-steer actions are logged to git-steer-state/state/audit.jsonl. Review periodically:

# In Claude
"Show git-steer logs"

# Or directly
gh api repos/YOUR-USERNAME/git-steer-state/contents/state/audit.jsonl \
  --jq '.content' | base64 -d | tail -20

---

Next Steps

You’re all set! Here are some things to try:

1. Security sweep: “Scan all my repos for vulnerabilities”
2. Branch cleanup: “Delete all branches older than 30 days in [repo]”
3. Repo creation: “Create a new private repo called my-project”
4. PR creation: “Commit a README.md to my-project with content…”

For advanced usage patterns, see the next post in this series: Advanced Patterns.

---

Repository: github.com/ry-ops/git-steer

Issues? Open a ticket at github.com/ry-ops/git-steer/issues