Proposal for Deprecating check-github-workflows and check-renovate Hooks

@sirosen

Thank you for the thoughtful response on issue #583 and for being open to a more detailed discussion. I appreciate the points you @sirosen raised. This proposal aims to address them directly and articulate a clear path forward that I believe will benefit both the users and the project.

1. A Clear, Two-Phase Deprecation Plan

I agree that a sudden removal would be disruptive. A graceful deprecation process is essential to accommodate existing users. I propose the following two-phase plan:

Phase 1: Announce Deprecation and Implement Warnings. In the next release, we can officially begin the deprecation process. This involves two key actions:
- Update Documentation: The documentation will be updated to clearly mark the check-github-workflows and check-renovate hooks as deprecated. It will recommend migrating to actionlint and renovate-config-validator and explain the rationale.
- Implement Runtime Warnings: A clear, non-disruptive deprecation warning will be added to the output when these hooks are used. The message will inform users of the deprecation, suggest the alternative tool, and reference the future removal.
Phase 2: Final Removal. After a significant grace period to allow for user migration—for instance, one year from the deprecation release—the hooks can be completely removed from the project. This extended timeline provides ample opportunity for all users to transition at their own pace.

This phased approach ensures that existing users are well-informed and have sufficient time to transition, minimizing any negative impact.

2. Long-Term User Benefits of Migrating

The primary motivation for this proposal is the significant long-term benefit for users, who will be guided towards more powerful and purpose-built tools.

More Comprehensive Validation: Tools like actionlint offer far more than just schema validation; they perform deep static analysis, checking for syntax errors, logical issues, and best practice violations in GitHub Actions workflows. Similarly, renovate-config-validator is the official, first-party tool for validating Renovate configurations. These tools help users catch a wider range of potential errors before they cause problems in production.
Staying Current with Official Tooling: The official renovate-config-validator is maintained in lockstep with Renovate Bot itself. This is a crucial advantage. With check-renovate, there is often a delay between the introduction of new Renovate features and the corresponding schema update in check-jsonschema. This can lead to validation failures where users trying to adopt new Renovate functionalities are blocked by an outdated schema, forcing them to wait for a new release of check-jsonschema. Migrating to the official tool eliminates this friction entirely.

3. Benefits for the `check-jsonschema` Project

While the primary motivation is user benefit, deprecating these specialized hooks also brings clear advantages to the check-jsonschema project itself.

Focus on the Core Mission: check-jsonschema excels as a general-purpose JSON Schema validator. Freeing up maintainer time and resources allows for more focus on improving the core functionality of the tool, developing other valuable features, and addressing general issues. This strengthens the project's primary value proposition.
Benefit to the Broader Open-Source Community: This change benefits the entire open-source community by avoiding duplicated effort for a subordinate substitute and ensuring that support requests are handled by the respective experts for each tool.

In summary, I believe a well-communicated, gradual deprecation of these hooks is in the best interest of both the users and the check-jsonschema project. It guides users toward superior tooling while allowing check-jsonschema to focus on its core strengths.

I hope this detailed proposal clarifies my perspective, and I would be happy to discuss this further.

@vivodi

I have taken a long time in responding, partly because I needed to take some time to decide what I think.

First, @vivodi thank you for your thoroughness, but even more than that, thank you for caring about this project and its users. ❤️

I don't agree with the vision you've laid out here in specific ways. I think we can still make improvements and find partial agreement.

Primarily, the end state in this proposal is the issue for me. Ultimately, after such changes are implemented, check-jsonschema will have fewer capabilities. If other projects like actionlint are unsuitable for users for some reason, it will not be obvious to them how to use check-jsonschema to suit their needs. In the envisioned end state, users have fewer options, which I think is bad.

That said, I very much agree that many users who are using check-jsonschema would benefit from learning about other linters which are more capable. At present, I know of actionlint and zizmor for GitHub Actions, and renovate-config-validator for Renovate. There may be many more for the various other hooks.

I also don't think that the tool runtime behaviors are the best way to point users to alternatives. I think that's a job best served by the docs.

The synthesis of all of that is that I believe we can redirect effort towards documentation thusly:

Add a new page to the docs, working title: "Alternatives"
Note that there are many other JSON Schema tools listed in the JSON Schema Official Docs
Add a section for each supported hook, pointing at alternative tools with a short description of each

Once that page is written up, I would be open to considering a meta-hook provided by check-jsonschema for pre-commit specifically: forbid-hooks-with-alternatives. That could read the .pre-commit-config.yaml and see if there are any listed hooks which we know (as of that version) have documented alternatives. It can fail if it finds any after printing a link to the "Alternatives" doc page. Because we wouldn't be baking this into existing hooks, this gives us freedom to add options specific to such a rule, like --exclude, so that config could finally materialize as

repos:
  - repo: https://github.com/python-jsonschema/check-jsonschema
    rev: ...?...
    hooks:
      - check-github-workflows
      - forbid-hooks-with-alternatives
        args: ["--exclude", "check-github-workflows"]

What do you think? Does this overall direction of

A doc page for alternative tools
A meta-hook (in a later release) to point users to those alternative tools, opt-in

sound satisfactory?

Thanks a lot for the thoughtful response. 🙏

I think your proposal of focusing on documentation and possibly adding a meta-hook later makes good sense. The idea of an “Alternatives” page with references to other tools seems like a practical compromise that avoids reducing functionality while still helping users discover better-suited linters.

I’m on board with this direction.

@sirosen

I was having some issues with renovate-config-validator official hook and found myself on this issue. That hook requires Node.js setup and installs the renovate npm package. It's currently the heaviest hook in my stack, and it's taking a unnecesarily long time to install compared to the others.

Even with a warm cache,

# Local, M1 Pro
Validate Renovate Config.................................................Passed
- hook id: check-renovate
- duration: 0.16s

  ok -- validation done
renovate-config-validator................................................Passed
- hook id: renovate-config-validator
- duration: 1.55s

   INFO: Validating renovate.json5 as global config
   INFO: Config validated successfully

# GitHub Actions
Validate Renovate Config.................................................Passed
- hook id: check-renovate
- duration: 0.63s
  ok -- validation done
renovate-config-validator................................................Passed
- hook id: renovate-config-validator
- duration: 2.59s
   INFO: Validating renovate.json5 as global config
   INFO: Config validated successfully

The official solution takes 4x-10x longer. When the goal is to validate the json schema, check-jsonschema with an up-to-date schema performs much better, and I'll prefer to use it over the official one. Removing the faster, lighter solution would have a negative impact on users, IMO.

+1 on the direction @sirosen drew.

Switch to check-jsonschema for Renovate schema validation

Navigation Menu

Repository navigation

Proposal for Deprecating `check-github-workflows` and `check-renovate` Hooks #586

1. A Clear, Two-Phase Deprecation Plan

2. Long-Term User Benefits of Migrating

3. Benefits for the `check-jsonschema` Project

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Proposal for Deprecating check-github-workflows and check-renovate Hooks #586

Description

1. A Clear, Two-Phase Deprecation Plan

2. Long-Term User Benefits of Migrating

3. Benefits for the check-jsonschema Project

Activity

sirosen commented on Sep 18, 2025

vivodi commented on Sep 18, 2025

ulgens commented on Feb 15, 2026

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions

Proposal for Deprecating `check-github-workflows` and `check-renovate` Hooks #586

3. Benefits for the `check-jsonschema` Project