Renovate GitHub Actions Guide Skill

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:

# 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:

ls -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:

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

IMPORTANT: Support Fork PRs

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

jobs:
  # 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:

Renovate 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: 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:

# 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:

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
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"
See complete implementation guide:
- references/BRANCH_PROTECTION.md for detailed examples and patterns
- assets/workflows/ci-unified-example.yml for working example

Repository settings:

# 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:

# 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:

# 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:

# 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:

Hosted Renovate App (simplest):
- Install Renovate GitHub App
- Select repositories → Done
- Skip to Step 3

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:

# 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:

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

Find exact username after first run:

gh 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:

# 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 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:

# 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 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:

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

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

Step 5: Validate configuration

Check Renovate config:

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

Verify GitHub settings:

# 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):

# 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.

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.

Agent Skills: Renovate GitHub Actions Guide

Install this agent skill to your local

Skill Files