Contributing to gitops-check

Thanks for taking the time to contribute.

What this project is

A single-file Python CLI that validates GitOps repository structure: controller detection, secret externalization, plaintext secret scan, config separation. Zero dependencies, MIT licence.

Getting started

git clone https://github.com/rahmankhanjohn/gitops-check.git
cd gitops-check
python -m unittest test_gitops_check -v

All tests should pass on Python 3.9 or newer. No install step.

Rules of the codebase

1. No dependencies. Standard library only. If a feature needs a third-party package, it does not go in this repo.
2. Manual sys.argv parsing. The tool uses direct argument parsing, not argparse. Keep it that way for consistency.
3. Single file. gitops_check.py is the whole tool. Keep it that way.
4. Every feature needs a test. Add a test in test_gitops_check.py that fails without your change.
5. Exit codes matter. 0 = pass, 1 = fail, 2 = error. Do not break this contract.
6. Plain English in output. Every number carries a plain sentence explaining what it means. No jargon without a gloss.
7. No em dashes. Use periods or commas.

How to contribute

1. Fork the repository.
2. Create a branch: git checkout -b feat/your-change.
3. Make your change. Add or update tests.
4. Run the full suite: python -m unittest test_gitops_check -v.
5. Run the smoke test: python gitops_check.py . --report.
6. Open a pull request with a short description of what you changed and why.

What we are looking for

• Additional checks and validation rules
• Better heuristics for edge cases
• Additional output formats
• Documentation improvements
• Bug reports with reproduction steps

What we are not looking for

• New dependencies
• Rewriting the tool in another language
• Features that require elevated privileges

Reporting bugs

Open a GitHub issue with:

• The command you ran
• The output you got
• The output you expected
• Your Python version and operating system

Code of conduct

Be direct, be specific, be kind. This is a tool for operators who are already having a hard quarter. Don't make them work harder to use it.