JimsGarage/CONTRIBUTING.md

Contributing

Thanks for contributing to JimsGarage! This guide covers the automated checks that run on pull requests and — importantly for this repo — how to handle the dummy credentials that many of these tutorials intentionally ship.

Linting

A pre-commit configuration (.pre-commit-config.yaml) and a GitHub Actions workflow (.github/workflows/lint.yml) run a set of checks. CI lints only the files changed in your PR, so you are not responsible for pre-existing issues in files you do not touch.

To run the checks locally before pushing:

pip install pre-commit
pre-commit install            # optional: run automatically on every commit
pre-commit run --all-files    # or scope to changed files (CI behavior)

The hooks include general hygiene (trailing whitespace, end-of-file newline), yamllint, shellcheck, actionlint, and gitleaks (secret scanning).

Credentials and secrets

Never commit a real credential. If you accidentally commit one, treat it as compromised: rotate it, then remove it from history.

Many tutorials here include throwaway / dummy credentials so a config works out of the box when copied. That is fine — but because they live next to real config, the gitleaks scanner cannot tell a deliberate dummy from a genuine leak. You therefore need to mark intentional dummies explicitly. There are two ways to do this; prefer the first.

1. Inline annotation (preferred)

For a dummy value in a comment-capable file that is already lint-clean, add a trailing # gitleaks:allow on the offending line:

environment:
  - "ADMIN_TOKEN=not-a-real-token-1234567890"  # gitleaks:allow

This is self-documenting at the point of use and is the convention for any new dummy credential you add.

2. Baseline in .gitleaksignore

Some findings cannot or should not be annotated inline. For these, add the finding's fingerprint to .gitleaksignore. Use this when the file is:

• JSON — it has no comment syntax (e.g. Netbird/management.json).
• A multi-line PEM private-key block — an inline marker is unreliable across the block (e.g. Authelia/Authelia/configuration.yml).
• Burdened with pre-existing lint debt — editing it would pull the whole file into the changed-files lint scope and fail unrelated yamllint/hygiene checks.

To get a fingerprint, scan and copy the Fingerprint field for the finding:

gitleaks dir . --report-format json --report-path /tmp/gitleaks.json
# copy the "Fingerprint" value into .gitleaksignore, with a brief comment

Allowlisted paths

.gitleaks.toml already allowlists conventional placeholder locations — tracked .env files and *example* / *sample* files — since those are dummy by convention in this repo. Secrets placed there are not scanned, so do not rely on them to hold anything real.