Build Custom Mihomo Rule Providers: YAML, GitHub & CI

Why build custom Mihomo rule providers instead of growing one profile forever

A Mihomo rule provider is a reusable collection of routing rules that a configuration can load as a unit. Instead of copying a long list of domains into every profile, you keep those rules in a separate YAML file, publish it at a stable URL, and reference it with RULE-SET. The result is easier to review, update, share between devices, and test before a change reaches your everyday configuration.

This is useful when you maintain separate rules for work services, development tools, streaming platforms, or domains that should always use a particular policy group. It is also useful when a team needs one shared list but wants to keep its main Mihomo configuration readable. A provider does not replace the rest of your profile: it supplies rules, while your main configuration still defines the proxy groups those rules should select and the order in which rules are evaluated.

That separation is important because routing depends on more than whether YAML parses. A provider can be valid YAML yet contain an unsupported rule, an incorrect domain, or a rule-set reference that points to a proxy group that does not exist. A rule can also be valid and still never match because an earlier, broader rule catches the request first. Treat providers as maintained configuration artifacts, not as a place to paste an unreviewed list and hope it works.

The examples below use a public GitHub repository and a Mihomo configuration with a group named PROXY. Change that name to match your own profile. Before publishing, check the Mihomo version used by your client or router: Clash Verge Rev, OpenClash, and other Mihomo-based clients may bundle different core versions or expose different update controls. Keeping the provider syntax compatible with the core that actually loads it is more useful than relying on a GUI label alone.

Choose a behavior and keep the provider narrowly scoped

Start by deciding what kinds of rules belong together. A provider is easier to reason about when its name describes one purpose, such as work-services or development-sites, rather than combining unrelated destinations into a generic “misc” file. Narrow scope helps you review changes, identify the source of an unexpected route, and reuse only the rule families a particular profile needs.

Mihomo supports different provider behaviors for different rule types. A domain provider contains domain-oriented entries, an ipcidr provider contains IP network entries, and a classical provider can contain supported rule lines such as domain, IP, process, or network rules. Do not select a behavior just because its name sounds broad: match the provider behavior to the rule syntax in the file, and verify support against the Mihomo version you run.

Provider behaviorTypical entriesGood fitReview carefully
domainDomain names and suffixesA list focused on hostnamesUse the domain-provider format your core expects; do not assume every rule keyword belongs here.
ipcidrIPv4 or IPv6 network rangesNetworks maintained separately from domain rulesCheck CIDR notation, address family, and any required no-resolve behavior.
classicalSupported rule lines such as DOMAIN-SUFFIXMixed or explicitly typed rule listsConfirm each rule type is supported by your target core and is written in the expected form.

For a first provider, use a small domain-focused list. A rules file using the YAML list format can look like this:

payload:
  - DOMAIN-SUFFIX,example.dev
  - DOMAIN,api.example.dev
  - DOMAIN-KEYWORD,docs

Use the schema expected by the behavior and Mihomo release you target. Some provider examples and existing configurations use a top-level YAML list rather than a payload key; the correct form is not something to infer from a filename. Confirm it in the documentation for the core version you deploy, then keep your repository examples and CI checks consistent with that choice. A file that parses as YAML is not automatically a valid rule provider.

Be precise about matching scope. DOMAIN targets one exact hostname, while DOMAIN-SUFFIX is intended for a hostname and its subdomains. DOMAIN-KEYWORD can match more broadly than its short name suggests, so use it only when that breadth is intentional. Avoid adding a parent suffix simply because one subdomain failed; first inspect the actual hostname in the client’s connection log. A narrowly scoped entry can solve the reported issue without routing unrelated services through the same group.

Give files and providers stable, descriptive names, and add a short note in the repository explaining ownership and intent. Avoid putting credentials, subscription URLs, private hostnames, or other secrets in a public repository. If a list is private, choose an access method supported by your core and deployment process; do not assume that a private GitHub raw URL will be fetchable without authentication.

Publish a GitHub rule file and connect it to Mihomo

Create a repository with a predictable structure, for example providers/work-services.yaml. Commit the provider file and a short README that explains what the entries cover, which Mihomo version you test against, and how changes are reviewed. For a public repository, use the raw file URL for the exact branch and path, not the normal GitHub page that displays the file in a browser. Keep the branch name, file path, and URL in sync when you rename or move anything.

In the main configuration, declare the provider under rule-providers and reference it from the ordered rules list. For example:

rule-providers:
  work-services:
    type: http
    behavior: classical
    format: yaml
    path: ./rules/work-services.yaml
    url: "https://raw.githubusercontent.com/OWNER/REPOSITORY/main/providers/work-services.yaml"
    interval: 86400

rules:
  - RULE-SET,work-services,PROXY
  - MATCH,DIRECT

Replace the placeholder owner and repository with the real public path. The local path is where Mihomo can store or read the provider file; choose a location suitable for your installation and preserve it when moving configuration between devices. interval controls how often an HTTP provider is refreshed in seconds. A daily interval is a reasonable starting point for a list that changes occasionally, while a frequently updated list may need a shorter interval. Excessive polling rarely improves routing and can create unnecessary requests.

The last argument of RULE-SET is a policy target, usually a proxy group or another supported outbound target. That target must exist in your configuration. If your group is named 🚀 Select, referencing PROXY will not magically create a group with that name; the configuration may fail validation or the rule may not behave as expected. Keep the provider name in RULE-SET identical to its key under rule-providers, including spelling and punctuation.

Rule order matters because Mihomo evaluates rules from top to bottom and uses the first matching rule. Put a specific provider rule before a broader rule that would capture the same traffic, such as a general domain rule or a final catch-all. A provider placed after MATCH is unreachable. When a destination takes the wrong route, inspect the matched rule in the client’s connection view before rearranging the entire configuration; the log often reveals whether the provider matched, whether a broader rule ran first, and which policy group was selected.

After adding the provider, update or reload the configuration through the client you use, then check its provider status and connection log. Some clients expose a button to refresh rule providers; others refresh them when the configuration loads or according to the configured interval. Do not treat a successful configuration import as proof that the remote file downloaded successfully. Verify the provider is healthy, confirm the loaded rules are the revision you expect, and test a hostname that should match as well as one that should not.

Add CI checks for YAML syntax and configuration references

GitHub Actions can catch common mistakes before a provider change is merged. A practical first layer is a YAML parser: it detects indentation errors, malformed strings, and other syntax problems that may be easy to miss in a code review. A second layer should check the contract between provider files and the main configuration: provider names must be unique, each referenced provider must be declared, and every rule-set target should name a defined policy group or an allowed built-in target.

For a repository containing only provider files, a small workflow can parse every YAML file in the provider directory. Pin the Python dependency or use a lock file if you need reproducible CI behavior, and run the workflow on pull requests as well as pushes to the default branch.

name: Validate rule providers

on:
  pull_request:
  push:
    branches: [main]

jobs:
  yaml:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: "3.12"
      - run: python -m pip install PyYAML
      - name: Parse provider YAML
        run: |
          python - <<'PY'
          from pathlib import Path
          import yaml

          files = sorted(Path("providers").glob("*.yaml"))
          if not files:
              raise SystemExit("No provider YAML files found")
          for path in files:
              with path.open(encoding="utf-8") as stream:
                  yaml.safe_load(stream)
              print(f"OK: {path}")
          PY

Parsing is necessary but not sufficient. PyYAML checks YAML syntax; it does not know whether a provider uses a Mihomo-supported behavior, whether a rule keyword is valid, or whether the provider’s content follows the schema expected by your core. Add a structural validator that checks the selected format and rejects unexpected top-level values. For a provider that must be a list of classical rules, for example, fail the build if the parsed document is a dictionary or if an entry is not a string in the format your project allows.

Reference validation requires looking at both sides of the configuration. Load the main profile, collect the keys under rule-providers and the names declared under proxy-groups, then inspect each RULE-SET rule. Fail if a rule refers to a provider key that is absent or to a group that is not defined. Account for built-in targets and any project-specific naming conventions rather than hard-coding every possible valid destination as a group. A simple validator that correctly checks your own profile is more valuable than an ambitious script that silently accepts broken references.

If you keep the main configuration in the same repository, you can add a pinned Mihomo binary or container to CI and run its configuration test command against the exact file you deploy. Pin the version to match your target core, record how the binary is obtained, and update it deliberately. A test against a much newer core may approve features that an older router cannot parse; a test against an older core may reject syntax that is intentionally required by your deployment. CI should model the runtime, not merely whichever binary is easiest to download that day.

Keep CI output useful. Print the filename and failing provider name, and identify whether the failure is YAML parsing, provider structure, a missing reference, or a core validation error. Avoid dumping secrets from environment variables or private configuration into public logs. When a check fails, fix the source file and rerun the workflow instead of weakening validation until the build turns green. If a rule is intentionally unusual, document why it is allowed so the next maintainer does not remove it as an apparent mistake.

Maintain updates without turning a small ruleset into a mystery

Review every rule change with the same care as a change to the main profile. Ask what user-visible problem it addresses, whether the hostname was observed in a log, whether a narrower rule would work, and which policy group should receive the traffic. A large copied list can hide stale entries and overly broad patterns. Prefer a small set of explainable rules, and remove entries when their purpose is no longer clear rather than accumulating them indefinitely.

For teams, use pull requests and require at least one review for changes to shared providers. Include a short test plan: the hostname to check, the expected rule match, and the expected outbound group. For personal repositories, the same information in a commit message is enough to make later troubleshooting faster. If a change affects a sensitive or business-critical service, test it on one profile before making it the default for every device.

Keep a known-good provider revision available. If an update sends traffic to the wrong group, reverting the commit or pinning the URL to a reviewed revision is usually safer than making several speculative edits at once.

When a provider fails, separate the failure into layers. First, check whether the URL is reachable from the device running Mihomo; a browser on your laptop may have a different network path from a router. Next, confirm that the response is the intended YAML file rather than a GitHub error page, redirect page, or rate-limit message. Then inspect the local provider status and Mihomo logs for download, parsing, or rule-evaluation errors. Finally, verify the rule order and target group. Changing a domain entry cannot repair an inaccessible URL, and changing the URL cannot fix a missing proxy group.

Common causes include a raw URL pointing at the wrong branch, a file path that changed after a repository reorganization, invalid YAML indentation, a provider behavior that does not match its rule content, and a typo in the provider key. Another subtle cause is correct syntax with incorrect scope: a broad suffix or keyword may route far more traffic than intended, while an exact-domain rule may miss a required subdomain. Compare the actual hostname in logs with the entry you wrote instead of testing only the website’s home page.

Use clear update boundaries. If a provider is served from a moving branch, every refresh may retrieve new content without an explicit change to the main configuration. That is convenient for routine maintenance, but it means reviews and CI on the repository are essential. For deployments requiring a fixed, auditable snapshot, use a versioned release or commit-specific source when it is compatible with your delivery setup. In either case, preserve a rollback path and know how to refresh the provider manually after a correction.

Rule providers also do not guarantee that an application will use the intended route. DNS resolution, connection reuse, application-level proxies, and traffic that does not pass through the Mihomo core can affect what you observe. Test with the client’s connection log and a controlled request, and distinguish a routing mismatch from DNS failure, a blocked destination, or an application cache. Good diagnostics keep a small rule change from turning into unnecessary edits to DNS, TUN, and proxy-group settings.

Some all-in-one proxy clients make basic routing feel simpler, but their custom-rule workflows can be limited, difficult to review, or tied to one device’s interface. Clash configurations can become cumbersome too when every rule is pasted into one profile and changes are made without checks. Mihomo rule providers offer a more maintainable alternative: separate YAML lists, shareable GitHub history, explicit rule ordering, and CI checks for syntax and references. If you want to build and test that workflow with a compatible client, visit the download page to choose a suitable build. Keep the rollout small, verify provider status and matching logs, and then expand the ruleset as your needs become clear.

→ Download Clash for free and enjoy a better internet experience

Go to Download Page