---

name: renovate-github-action-guide description: Apply the "GitHub Actions and Renovate Guide" to configure repo settings, branch protection, GitHub App/PAT secrets, renovate.json5, and optional CI auto-fix workflow for personal or team GitHub projects. Use when asked to introduce Renovate, enable dependency auto-updates, auto-fix dependency failures, or align settings with the guide.

Renovate GitHub Actions Guide

Prerequisites

Required:

• GitHub CLI installed and authenticated: gh auth login
• Repository admin access
• Token scopes: repo, admin:org (for org repos), workflow

Quick verification:

Copy# Check admin access and required scopes
gh auth status
gh api repos/$OWNER/$REPO | jq -e '.permissions.admin == true' || echo "Need admin access"

If setup fails: See references/GH_CLI_SETUP.md for detailed authentication troubleshooting and permission requirements.

Quick Start

1. Check existing setup:

Copyls -la renovate.json* .github/renovate.json* .renovaterc* 2>/dev/null
gh pr list --author "renovate[bot]" --limit 5

2. Identify project type:

• Personal: Single maintainer
• Team: Multiple maintainers, requires reviews
• Public (single maintainer): Can use hosted Renovate App → Skip to Step 3

3. Collect inputs:

• Repo: owner/name, default branch
• CI: workflow names
• Schedule: timezone, auto-merge policy

4. Follow workflow steps below

Public Repository (Single Maintainer) - Simplified Setup

If your repository is public with a single maintainer, you can use a much simpler setup:

What you can skip:

• GitHub App setup (use hosted Renovate App instead)
• Fine-grained PAT for approvals
• GitHub Environment for secrets
• Renovate GitHub Actions workflow
• Complex branch protection rules

Minimal setup steps:

1. Enable auto-merge in repository settings
2. Install the Renovate GitHub App
3. Add .github/renovate.json5 or renovate.json to your repository
4. (Optional) Configure basic branch protection for required status checks

IMPORTANT: Support Fork PRs

If accepting contributions from forks, add fork-aware conditions to workflows:

Copyjobs:
  # Jobs that need secrets (should NOT run on fork PRs)
  auto-merge:
    if: |
      github.event_name != 'pull_request' ||
      ! github.event.pull_request.head.repo.fork
    steps:
      # Uses secrets - safe from fork access

  # Jobs that don't need secrets (SHOULD run on fork PRs)
  tests:
    # No condition - runs on all PRs including forks
    steps:
      # No secrets used - safe for forks

Why this matters:

• Fork PRs can't access repository secrets (security feature)
• Workflows with secrets will fail on fork PRs
• Tests and checks should run on forks
• Auto-merge and approval jobs should skip forks

See references/guide.md "Fork PR conditions" section for complete patterns.

See references/guide.md "Public repository (single maintainer)" section for complete details.

Workflow

Copy this checklist and track your progress:

CopyRenovate Setup Progress:
- [ ] Prerequisites: gh CLI authenticated, admin access verified
- [ ] Step 1: Repository settings + status-check job + branch protection
- [ ] Step 2: GitHub App setup + secrets (or use hosted app)
- [ ] Step 3: Add renovate.json5 (choose preset)
- [ ] Step 4: (Optional) Self-hosted workflow
- [ ] Step 5: (Optional) CI auto-fix workflow
- [ ] Step 6: Validation + test PR

Step 1: Apply repository settings and branch protection rules

Required permissions:

• Repository: Admin access
• Scope: repo (full control)
• Organization: "Repository" → "Administration" permission

Verify before proceeding:

Copy# Must return true
gh api repos/$OWNER/$REPO | jq '.permissions.admin'

CRITICAL: Implement status-check job pattern first

Before configuring branch protection, you MUST add a status-check job to your CI workflows:

1. Why it's required:

   • Prevents accidental merges when re-running failed jobs
   • Provides a single, reliable status check for branch protection
   • Ensures ALL required checks pass before merge

2. Implementation options:

   Option A: Unified workflow (recommended for new projects)

   • Use assets/workflows/ci-unified-example.yml as template
   • Consolidates all CI checks into one workflow
   • Uses dorny/paths-filter for conditional execution
   • Single status-check job depends on all checks

   Option B: Add status-check to existing workflows (easier migration)

   • Keep existing workflow files
   • Add a status-check job to each workflow
   • See references/BRANCH_PROTECTION.md "Migration Strategy"

3. See complete implementation guide:

   • references/BRANCH_PROTECTION.md for detailed examples and patterns
   • assets/workflows/ci-unified-example.yml for working example

Repository settings:

Copy# Enable auto-merge (requires admin access)
gh api -X PATCH repos/$OWNER/$REPO -f allow_auto_merge=true
# If error 403: Need repository admin access
# If error 404: Repository not found or no access

Branch protection for default branch:

After implementing status-check job:

Copy# Personal project (basic)
# Requires: admin access, repo scope
gh api -X PUT repos/$OWNER/$REPO/branches/$BRANCH/protection \
  --input - <<EOF
{
  "required_status_checks": {
    "strict": true,
    "contexts": ["status-check"]
  },
  "enforce_admins": true,
  "required_pull_request_reviews": {
    "required_approving_review_count": 0
  },
  "restrictions": null,
  "allow_force_pushes": false,
  "allow_deletions": false
}
EOF

For team projects with reviews, see references/BRANCH_PROTECTION.md.

For team projects only: Add dedicated branch protection for renovate/* branches:

Copy# Requires: admin access, repo scope
gh api -X PUT repos/$OWNER/$REPO/branches/renovate%2F*/protection \
  --input - <<EOF
{
  "required_status_checks": null,
  "enforce_admins": false,
  "required_pull_request_reviews": null,
  "restrictions": {
    "users": [],
    "teams": [],
    "apps": ["renovate"]
  },
  "allow_force_pushes": {"enabled": true},
  "allow_deletions": {"enabled": true}
}
EOF

Validation:

Copy# Verify auto-merge is enabled
gh api repos/$OWNER/$REPO | jq '.allow_auto_merge'

# Check branch protection
gh api repos/$OWNER/$REPO/branches/$BRANCH/protection | jq '{required_status_checks, enforce_admins}'

# Verify status-check is the required check
gh api repos/$OWNER/$REPO/branches/$BRANCH/protection | jq '.required_status_checks.contexts'
# Expected: ["status-check"]

Step 2: Set up GitHub App and secrets

Choose authentication method:

1. Hosted Renovate App (simplest):

   • Install Renovate GitHub App
   • Select repositories → Done
   • Skip to Step 3

2. Self-hosted with GitHub App (full control):

   Quick setup: a. Create app: https://github.com/settings/apps/new

   • Name: renovate-bot-<username> (globally unique)
   • Permissions: contents: write, pull-requests: write, workflows: write (optional)
   • Webhook: Disabled

   b. Generate private key → Download .pem file

   c. Install app to repositories

   d. Store secrets:

   Copy# Personal project
   gh secret set RENOVATE_APP_ID --body "<app-id>"
   gh secret set RENOVATE_APP_PRIVATE_KEY < private-key.pem
   
   # Team project (environment) - protects secrets with branch policy
   gh api -X PUT repos/$OWNER/$REPO/environments/renovate --input - <<EOF
   {"deployment_branch_policy": {"protected_branches": false, "custom_branch_policies": true}}
   EOF
   gh secret set RENOVATE_APP_ID --env renovate --body "<app-id>"
   gh secret set RENOVATE_APP_PRIVATE_KEY --env renovate < private-key.pem
   

   e. Configure bot username in renovate.json5:

   Copy{"username": "renovate-bot-<your-username>[bot]"}
   

   Find exact username after first run:

   Copygh pr list --author "renovate" --json author --jq '.[0].author.login'
   

Detailed guide: See references/GITHUB_APP_SETUP.md for troubleshooting, permission details, and alternative setups.

Step 3: Add and customize renovate.json5

Check for existing configuration first:

Copy# Check for existing Renovate config
if [ -f renovate.json ] || [ -f .github/renovate.json5 ] || [ -f .renovaterc ]; then
  echo "Renovate config already exists. Validating..."
  # Skip to validation step
else
  echo "No Renovate config found. Creating new configuration..."
fi

If configuration already exists, validate it with Step 5 and skip the rest of this step.

Choose configuration preset:

• assets/renovate.json5 - Minimal (extends external config)
• assets/renovate-conservative.json5 - Conservative updates (stable dependencies)
• assets/renovate-aggressive.json5 - Aggressive updates (latest versions quickly)

Place config file:

Copy# Copy chosen preset to your repository
cp assets/renovate-conservative.json5 .github/renovate.json5

Customize as needed:

• Schedule: Adjust timezone and frequency
• Labels: Add project-specific labels
• Auto-merge: Configure which update types to auto-merge
• Bot username: Set when using GitHub App (see guide)

Validation:

Copy# Validate JSON5 syntax
npx -p renovate renovate-config-validator .github/renovate.json5

Step 4: (Optional) Add Renovate GitHub Actions workflow

When to use:

• Self-hosting Renovate (not using hosted Renovate App)
• Need custom runner or private registry access

Setup:

Copy# Copy workflow template
mkdir -p .github/workflows
cp assets/workflows/renovate.yml .github/workflows/renovate.yml

Configure workflow:

• Update secret names to match Step 2
• Adjust schedule (default: daily at 2 AM)
• Set repositories parameter if managing multiple repos

See references/renovate-action.md for action inputs and GitHub App token usage.

Validation:

Copy# Check workflow syntax
actionlint .github/workflows/renovate.yml

# Trigger manual run to test
gh workflow run renovate.yml

Step 5: (Optional) Add CI auto-fix workflow

When to use:

• Auto-fix dependency update PRs when CI fails
• Reduce manual intervention for breaking changes in dependencies

How it works:

1. Triggered when CI workflow completes with failure on dependency bot PRs
2. Claude Code investigates the failure and attempts to fix it
3. Commits and pushes fixes to the PR
4. Auto-merge handles merging once all checks pass

Setup:

Copy# Copy workflow template
mkdir -p .github/workflows
cp assets/workflows/auto-fix-dependencies.yml .github/workflows/auto-fix-dependencies.yml

Required authentication (choose one):

Option A: Claude Code OAuth token (recommended)

Copy# Easiest: Use Claude Code's built-in command
/install-github-app

# Or manually create OAuth token at https://claude.ai/settings/oauth
gh secret set CLAUDE_CODE_OAUTH_TOKEN --body "<oauth-token>"

Option B: Anthropic API key

Copy# Create API key at https://console.anthropic.com/settings/keys
gh secret set ANTHROPIC_API_KEY --body "<api-key>"

Note: OAuth token setup via /install-github-app is the easiest method. API key requires manual management but works for direct API access.

Configure workflow:

• Update workflows array to match your CI workflow names
• Choose authentication method in the workflow file:
  • Use claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
  • OR use anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
• Adjust claude_args to allow necessary tools
• Set appropriate permissions

Validation:

Copy# Check workflow syntax
actionlint .github/workflows/auto-fix-dependencies.yml

# Test by triggering a failed CI (optional)

See assets/workflows/auto-fix-dependencies.yml for complete example.

Step 6: Validate configuration

Check Renovate config:

Copynpx -p renovate renovate-config-validator .github/renovate.json5

Verify GitHub settings:

Copy# Repository settings
gh api repos/$OWNER/$REPO | jq '{allow_auto_merge, default_branch}'

# Branch protection
gh api repos/$OWNER/$REPO/branches/$BRANCH/protection | jq '{required_status_checks, required_pull_request_reviews}'

# Secrets are configured
gh api repos/$OWNER/$REPO/actions/secrets | jq '.secrets[].name'

Test with dry-run (if self-hosting):

Copy# Add --dry-run to workflow for testing
# Or run locally:
npx renovate --dry-run --token=$GITHUB_TOKEN $OWNER/$REPO

Decision Notes

• If using the github-actions manager, ensure the token has workflow permissions.
• Ask before enabling auto-merge and agree on which updates are safe to merge automatically.

Assets

• assets/renovate.json5: starter Renovate config (minimal).
• assets/renovate-conservative.json5: conservative update strategy preset.
• assets/renovate-aggressive.json5: aggressive update strategy preset.
• assets/workflows/renovate.yml: Renovate GitHub Actions workflow template (self-hosting only).
• assets/workflows/ci-unified-example.yml: unified CI workflow with status-check job pattern.
• assets/workflows/auto-fix-dependencies.yml: CI auto-fix workflow using Claude Code Action (optional).

References

• references/guide.md: summarized settings from the guide (personal vs team).
• references/renovate-action.md: Renovate GitHub Action usage details.
• references/VALIDATION.md: validation commands and troubleshooting guide.
• references/BRANCH_PROTECTION.md: status-check job pattern and branch protection configuration.
• references/GITHUB_APP_SETUP.md: complete GitHub App creation and configuration guide.
• references/GH_CLI_SETUP.md: GitHub CLI authentication, required scopes, and permission requirements.