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](https://github.com/apps/renovate)
   - 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**:

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

2. **Create Renovate Bot Token**:
   - **For Organization Repositories**: See detailed guide → **[Gitea Token Setup](GITEA_TOKEN_SETUP.md)**
   - Required permissions: `repository` (Read/Write), `issue` (Read/Write), `organization` (Read), `user` (Read)
   - Save token securely for next step

3. **Create Environment Configuration**:

```bash
# ~/.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**:

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

```bash
# /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:

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

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

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

```bash
# 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

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

### Notification Integration

```json
{
  "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](https://docs.renovatebot.com/)
- [Configuration Options](https://docs.renovatebot.com/configuration-options/)
- [Package Rules](https://docs.renovatebot.com/configuration-options/#packagerules)