plex-playlist/docs/RENOVATE_SETUP_GUIDE.md

Renovate Bot Setup Guide

Overview

Renovate is an automated dependency update tool that creates pull requests to keep your project dependencies up to date. This guide covers setting up Renovate for the plex-playlist project with optimal configuration.

Repository Current Mode (2026-07)

This repository runs Renovate through .gitea/workflows/renovate.yml.

Current operational behavior:

1. Uses ubuntu-act-8gb runner due to npm/registry memory pressure.
2. Prepares Renovate container image with mirror-first strategy:

• primary: kankali.darkhelm.lan:3001/darkhelm.org/renovate:41
• fallback: ghcr.io/renovatebot/renovate:41

3. Uses digest-aware freshness checks before deciding whether local cached image is current.
4. Selects endpoint dynamically between internal and external candidates based on preflight reachability.
5. Selects token via preflight checks (repo access required) with fallback order from configured secrets.
6. Uses constrained memory settings (RENOVATE_NODE_ARGS) and disables OSV alerts in this runner profile.

Treat workflow behavior as source of truth; use this doc as operator guidance.

Setup Options

Option 1: GitHub App (Recommended for GitHub)

1. Install Renovate App:

   • Go to Renovate GitHub App
   • Click "Install" and select your repository
   • Choose repository access (single repo or organization-wide)

2. Configure Repository Access:

   • Select the plex-playlist repository
   • Grant necessary permissions (read/write to repository, pull requests, issues)

3. Initial Configuration:

   • Renovate will automatically detect the renovate.json file
   • Creates an onboarding PR to explain the configuration
   • Review and merge the onboarding PR to activate

Option 2: Self-Hosted (For Gitea/Custom Git Servers)

Since your project uses kankali.darkhelm.lan (Gitea), you'll need to run Renovate as a service:

Docker-based Self-Hosted Setup

1. Create Renovate Configuration:

# Create renovate directory
mkdir -p ~/.config/renovate

2. Create Renovate Bot Token:

   • For Organization Repositories: See detailed guide → Gitea Token Setup
   • Required permissions: repository (Read/Write), issue (Read/Write), organization (Read), user (Read)
   • Save token securely for next step

3. Create Environment Configuration:

# ~/.config/renovate/config.js
module.exports = {
  platform: 'gitea',
  endpoint: 'https://kankali.darkhelm.lan/api/v1',
  token: process.env.RENOVATE_TOKEN,
  gitAuthor: 'Renovate Bot <renovate@darkhelm.org>',
  repositories: ['DarkHelm.org/plex-playlist'],
  onboarding: false, // Skip onboarding PR
  requireConfig: 'required' // Use existing renovate.json
};

4. Run with Docker:

# Run Renovate Bot
docker run --rm \
  -e RENOVATE_TOKEN="your_gitea_token_here" \
  -v ~/.config/renovate/config.js:/usr/src/app/config.js \
  renovate/renovate:latest

Scheduled Automation

Create a systemd timer or cron job to run Renovate periodically:

# /etc/cron.d/renovate-bot
# Run Renovate every Monday at 8 AM
0 8 * * 1 root docker run --rm -e RENOVATE_TOKEN="$RENOVATE_TOKEN" -v ~/.config/renovate/config.js:/usr/src/app/config.js renovate/renovate:latest

Option 3: CI/CD Integration

Add Renovate to your existing Gitea Actions workflow:

# .gitea/workflows/renovate.yml
name: Renovate
on:
  schedule:
    - cron: "0 8 * * 1" # Monday 8 AM
  workflow_dispatch: # Manual trigger

jobs:
  renovate:
    runs-on: ubuntu-act-8gb
    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Run Renovate
        uses: renovatebot/github-action@v40.3.2
        with:
          configurationFile: renovate.json
          token: ${{ secrets.RENOVATE_TOKEN }}
        env:
          RENOVATE_PLATFORM: gitea
          RENOVATE_ENDPOINT: selected at runtime from internal/external candidates

Configuration Explanation

Key Features of Our Configuration

1. Smart Scheduling:

   • Regular updates: Weekday mornings before 9 AM
   • Security updates: Any time
   • Grouped updates: Monday mornings

2. Automerge Strategy:

   • Auto: Minor/patch updates for trusted packages (types, linting tools)
   • Manual: Major updates, Docker base images, security fixes

3. Grouping:

   • Python dev tools: ruff, pytest, mypy, etc.
   • Frontend dev tools: eslint, prettier, typescript, etc.
   • Docker base images: ubuntu, python, node versions

4. Custom Managers:

   • Detects Python/Node versions in Dockerfiles
   • Updates base image versions automatically

Package Manager Support

Our configuration handles:

• Python (uv): backend/pyproject.toml
• Node.js (Yarn): frontend/package.json + frontend/yarn.lock
• Docker: All Dockerfile.* files
• GitHub Actions: .gitea/workflows/*.yml (if using actions)

Testing the Configuration

1. Validate Configuration

# Install Renovate CLI for testing
npm install -g renovate

# Validate configuration
renovate-config-validator renovate.json

# Dry run (shows what would be updated)
renovate --dry-run --log-level=debug DarkHelm.org/plex-playlist

2. Expected Behavior

Once active, Renovate will:

1. Scan Dependencies: Daily check for updates
2. Create PRs: Individual PRs for each update group
3. Auto-merge: Safe updates (minor/patch) merge automatically
4. Security Alerts: Immediate PRs for vulnerability fixes
5. Dependency Dashboard: Issue with update status overview

3. Integration with CI/CD

Renovate PRs will trigger your existing CI/CD pipeline:

• Build and test in Docker containers
• Run full quality gates (linting, type checking, tests)
• Only merge if all checks pass

Monitoring and Maintenance

Dashboard

Renovate creates a "Dependency Dashboard" issue showing:

• Pending updates
• Failed PRs
• Ignored dependencies
• Configuration errors

Logs and Debugging

For self-hosted setup:

# Run with debug logging
docker run --rm \
  -e LOG_LEVEL=debug \
  -e RENOVATE_TOKEN="your_token" \
  -v ~/.config/renovate/config.js:/usr/src/app/config.js \
  renovate/renovate:latest

Common Issues

1. Node.js Version Compatibility:

   • Renovate 41+ requires Node.js 24.10.0+ or 22.13.0+
   • Use renovate@40.3.2 for older Node.js versions
   • Our CI workflow automatically handles this

2. Token Permissions: Ensure Gitea token has repo write access

3. Rate Limiting: Adjust prHourlyLimit if hitting API limits

4. Large Updates: Major version updates may need manual review

5. Docker Registry: Ensure base image updates don't break builds

Current Workflow-Specific Failures

1. Renovate image pull failures

• Symptom: both mirror and GHCR candidates fail.
• Check: runner DNS/egress and registry auth token validity.

2. Endpoint preflight failures

• Symptom: cannot reach both internal and external API endpoints.
• Check: endpoint host mapping, TLS mode, and runner network route.

3. Token access failures

• Symptom: API /repos/<org>/<repo> check returns non-200.
• Check: token scopes and secret ordering.

4. OOM or abrupt termination

• Symptom: process exits under memory pressure.
• Check: RENOVATE_NODE_ARGS, PR concurrency limits, and optional feature toggles.

Operator Notes

For this repository, prefer updating .gitea/workflows/renovate.yml over local one-off Renovate service changes. Keep docs and workflow in sync after changing:

• endpoint selection logic
• token preflight/fallback order
• image source policy (mirror/fallback)
• memory and concurrency guardrails

Quick Validation

For basic JSON validation without installing Renovate:

# Quick syntax check (no Renovate installation needed)
./scripts/quick-renovate-check.sh

# Full validation (requires Renovate installation)
./scripts/validate-renovate.sh

Security Considerations

1. Token Security: Store Renovate token in secrets management
2. Branch Protection: Ensure main branch requires PR reviews
3. Automerge Limits: Only automerge trusted, low-risk updates
4. Vulnerability Alerts: Enable immediate security update PRs

Advanced Configuration

Custom Rules Example

{
  "packageRules": [
    {
      "description": "Pin exact versions for critical packages",
      "matchPackageNames": ["fastapi", "@types/node"],
      "rangeStrategy": "pin"
    },
    {
      "description": "Ignore beta/alpha releases",
      "matchPackagePatterns": [".*"],
      "ignoreUnstable": true
    }
  ]
}

Notification Integration

{
  "notifications": [
    {
      "platform": "slack",
      "endpoint": "https://hooks.slack.com/services/...",
      "channels": ["#dev-notifications"]
    }
  ]
}

Next Steps

1. Choose Setup Method: GitHub App (if on GitHub) or self-hosted (for Gitea)
2. Generate API Token: Create token with appropriate permissions
3. Test Configuration: Run dry-run to verify setup
4. Monitor First Updates: Review initial PRs to ensure proper operation
5. Adjust Settings: Fine-tune automerge rules based on project needs

---

Related Documentation:

• Renovate Official Docs
• Configuration Options
• Package Rules