Creating a Config Templates Repository

This page explains how to create a repository compatible with the config-templates provider type. This lets you create reusable include files that can be shared across multiple Recyclarr configurations.

When You Need This

Use the config-templates type when you want to:

• Create reusable configuration snippets (includes) for quality profiles, custom format assignments, etc.
• Share standardized configurations across teams or the community

Required Structure

A config-templates compatible repository needs an includes.json file at the repository root. Recyclarr reads no other file from the repository; it finds include YAML files only through the paths listed in includes.json.

Directory Layout Example

my-templates-repo/
├── includes.json              # Maps include IDs to YAML files
├── radarr/
│   └── includes/
│       └── quality-profiles/
│           ├── hd-bluray.yml
│           └── uhd-bluray.yml
└── sonarr/
    └── includes/
        └── quality-profiles/
            └── tv-hd.yml

Include Files

Includes are partial YAML configurations that can be referenced from your main config using the include directive.

The includes.json File

Maps include IDs to their YAML file paths, with a separate list for each service:

{
  "radarr": [
    {
      "id": "radarr-quality-hd",
      "template": "radarr/includes/quality-profiles/hd-bluray.yml"
    },
    {
      "id": "radarr-quality-uhd",
      "template": "radarr/includes/quality-profiles/uhd-bluray.yml"
    }
  ],
  "sonarr": [
    {
      "id": "sonarr-quality-hd",
      "template": "sonarr/includes/quality-profiles/tv-hd.yml"
    }
  ]
}

An include listed under radarr can only be used in Radarr configurations, and likewise for sonarr. Either list may be omitted.

Include JSON Fields

Field	Required	Description
id	Yes	Identifier used in the config's include directive. Letters, digits, _, and - only
template	Yes	Path to the YAML file, relative to the repository root. Must not contain .. path segments

Recyclarr ignores any other fields in an entry.

Example Include YAML

An include file contains partial configuration that gets merged into the main config:

# radarr/includes/quality-profiles/hd-bluray.yml
quality_profiles:
  - name: HD Bluray
    reset_unmatched_scores:
      enabled: true
    upgrade:
      allowed: true
      until_quality: Bluray-1080p
      until_score: 10000
    min_format_score: 0
    quality_sort: top
    qualities:
      - name: Bluray-1080p
      - name: Bluray-720p

Using Includes in Config

Reference includes by their ID:

radarr:
  movies:
    base_url: http://localhost:7878
    api_key: !secret radarr_api_key

    include:
      - template: radarr-quality-hd

ID Naming Best Practices

When two providers define the same include ID for a service, only one of them is used (see Duplicate IDs). Use descriptive prefixes to keep your IDs distinct, such as radarr-quality-hd or sonarr-cf-anime.

Using Your Repository

Add your config-templates repository to settings.yml:

resource_providers:
  # As a supplemental source (adds to official)
  - name: my-templates
    type: config-templates
    clone_url: https://github.com/yourname/my-templates.git
    reference: main

  # Or as a replacement (replaces official)
  - name: my-templates
    type: config-templates
    clone_url: https://github.com/yourname/my-templates.git
    reference: main
    replace_default: true

For local directories:

resource_providers:
  - name: my-local-templates
    type: config-templates
    path: /home/user/my-templates

info

The official config-templates repository has no includes.json, so it provides no includes. The include examples on this page apply only to your own resource providers.

Duplicate IDs

If more than one provider defines the same include ID for the same service, the provider listed last in resource_providers wins. IDs are compared case-insensitively. See How Precedence Works for the full ordering rules.