From 34f83bfc4eb8087182fa50eb2e665380f1fdf9af Mon Sep 17 00:00:00 2001 From: sebastianMindee <130448732+sebastianMindee@users.noreply.github.com> Date: Wed, 22 Jul 2026 15:57:47 +0200 Subject: [PATCH 1/3] :wrench: switching over from pre-commit to ruby-only solution --- .git-hooks/pre_commit/gitleaks.rb | 19 +++++++++++ .github/workflows/_static-analysis.yml | 31 +++++------------ .overcommit.yml | 46 ++++++++++++++++++++++++++ .pre-commit-config.yaml | 36 -------------------- mindee.gemspec | 1 + 5 files changed, 74 insertions(+), 59 deletions(-) create mode 100644 .git-hooks/pre_commit/gitleaks.rb create mode 100644 .overcommit.yml delete mode 100644 .pre-commit-config.yaml diff --git a/.git-hooks/pre_commit/gitleaks.rb b/.git-hooks/pre_commit/gitleaks.rb new file mode 100644 index 000000000..d3e1d7591 --- /dev/null +++ b/.git-hooks/pre_commit/gitleaks.rb @@ -0,0 +1,19 @@ +# frozen_string_literal: true + +module Overcommit + module Hook + module PreCommit + # Local script to run gitleaks + class Gitleaks < Base + # Runs the command. + def run + result = execute(['gitleaks', 'git', '--staged', '-v', '.']) + + return :pass if result.success? + + [:fail, result.stdout + result.stderr] + end + end + end + end +end diff --git a/.github/workflows/_static-analysis.yml b/.github/workflows/_static-analysis.yml index d35199286..190010bbd 100644 --- a/.github/workflows/_static-analysis.yml +++ b/.github/workflows/_static-analysis.yml @@ -22,31 +22,16 @@ jobs: ruby-version: "3.2.0" bundler-cache: true - - name: Set up Python - uses: actions/setup-python@v5 - with: - python-version: "3.x" - - - name: Install pre-commit - run: | - python -m pip install --upgrade pip - python -m pip install pre-commit - - - name: Run pre-commit checks (security + hygiene) + - name: Run Gitleaks + uses: gitleaks/gitleaks-action@v2 env: - SKIP: rubocop,steep - run: | - pre-commit run --all-files --show-diff-on-failure + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} + GITLEAKS_EXCLUDE: "^(spec/data/|docs/code_samples/|local_test/)" - name: Analyse the code with Rubocop run: | bundle install - bundle exec rubocop ./ - - - name: Attempt to generate the documentation - run: | - bundle exec rake doc - - - name: Check types using Steep - run: | - bundle exec steep check + bundle exec overcommit --install + bundle exec overcommit --sign + bundle exec overcommit --sign pre-commit + SKIP=Gitleaks bundle exec overcommit --run diff --git a/.overcommit.yml b/.overcommit.yml new file mode 100644 index 000000000..5e40e126b --- /dev/null +++ b/.overcommit.yml @@ -0,0 +1,46 @@ +PreCommit: + MergeConflicts: + enabled: true + + YamlSyntax: + enabled: true + + TrailingWhitespace: + enabled: true + + FileSize: + enabled: true + byte_limit: 1048576 + + RuboCop: + enabled: true + required_executable: 'bundle' + command: ['bundle', 'exec', 'rubocop', '--force-exclusion', '--no-server'] + + CustomScript: + enabled: true + description: 'Run Steep type checking' + required_executable: 'bundle' + command: ['bundle', 'exec', 'steep', 'check'] + + Gitleaks: + enabled: true + required_executable: 'gitleaks' + CommitMsg: + enabled: false + CapitalizedSubject: + enabled: false + TextWidth: + enabled: false + TrailingPeriod: + enabled: false + SingleLineSubject: + enabled: false + EmptyMessage: + enabled: false + +PrePush: + BundleAudit: + enabled: true + required_executable: 'bundle' + command: ['sh', '-c', 'bundle exec bundle-audit check'] diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml deleted file mode 100644 index e013967a1..000000000 --- a/.pre-commit-config.yaml +++ /dev/null @@ -1,36 +0,0 @@ -repos: - - repo: https://github.com/pre-commit/pre-commit-hooks - rev: v6.0.0 - hooks: - - id: check-merge-conflict - - id: check-yaml - - id: end-of-file-fixer - - id: trailing-whitespace - - id: check-added-large-files - args: ["--maxkb=1024"] - - - repo: https://github.com/gitleaks/gitleaks - rev: v8.30.0 - hooks: - - id: gitleaks - exclude: ^(spec/data/|docs/code_samples/|local_test/) - - - repo: local - hooks: - - id: rubocop - name: RuboCop - entry: bundle exec rubocop --force-exclusion --no-server - language: system - pass_filenames: false - - id: steep - name: Steep - entry: bundle exec steep check - language: system - pass_filenames: false - stages: [pre-commit, pre-push] - - id: bundle-audit - name: Bundle Audit - entry: bundle exec bundle-audit check - language: system - pass_filenames: false - stages: [pre-commit, pre-push] diff --git a/mindee.gemspec b/mindee.gemspec index ed46b531c..b5f84741f 100644 --- a/mindee.gemspec +++ b/mindee.gemspec @@ -37,6 +37,7 @@ Gem::Specification.new do |spec| spec.add_dependency 'pdf-reader', '~> 2.15' spec.add_development_dependency 'bundle-audit', '~> 0.2.0' + spec.add_development_dependency 'overcommit', '~> 0.71' spec.add_development_dependency 'rbs', '~> 3.10' spec.add_development_dependency 'rubocop', '~> 1.86' spec.add_development_dependency 'steep', '~> 1.10' From 9d48ea7db22debb8b048b327812a340bbe3acc2c Mon Sep 17 00:00:00 2001 From: sebastianMindee <130448732+sebastianMindee@users.noreply.github.com> Date: Thu, 23 Jul 2026 10:05:58 +0200 Subject: [PATCH 2/3] fix license --- .github/workflows/_static-analysis.yml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/.github/workflows/_static-analysis.yml b/.github/workflows/_static-analysis.yml index 190010bbd..cf333f87b 100644 --- a/.github/workflows/_static-analysis.yml +++ b/.github/workflows/_static-analysis.yml @@ -23,10 +23,10 @@ jobs: bundler-cache: true - name: Run Gitleaks - uses: gitleaks/gitleaks-action@v2 + uses: gitleaks/gitleaks-action@v3 env: GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} - GITLEAKS_EXCLUDE: "^(spec/data/|docs/code_samples/|local_test/)" + GITLEAKS_LICENSE: ${{ secrets.GITLEAKS_LICENSE }} - name: Analyse the code with Rubocop run: | From bbb4295245a66f2974de29566cd98807e1a23f45 Mon Sep 17 00:00:00 2001 From: sebastianMindee <130448732+sebastianMindee@users.noreply.github.com> Date: Mon, 27 Jul 2026 19:20:54 +0200 Subject: [PATCH 3/3] update contributing guidelines + fix static analysis --- .github/workflows/_static-analysis.yml | 2 +- CONTRIBUTING.md | 128 +++++++++++++++++++++++++ 2 files changed, 129 insertions(+), 1 deletion(-) diff --git a/.github/workflows/_static-analysis.yml b/.github/workflows/_static-analysis.yml index cf333f87b..1fe36fa4e 100644 --- a/.github/workflows/_static-analysis.yml +++ b/.github/workflows/_static-analysis.yml @@ -26,7 +26,7 @@ jobs: uses: gitleaks/gitleaks-action@v3 env: GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} - GITLEAKS_LICENSE: ${{ secrets.GITLEAKS_LICENSE }} + GITLEAKS_LICENSE: ${{ secrets.GITLEAKS_LICENSE_KEY }} - name: Analyse the code with Rubocop run: | diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 776fa9dd0..5d571fa8b 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -68,6 +68,134 @@ Please follow these steps to have your contribution considered by the maintainer While the prerequisites above must be satisfied prior to having your pull request reviewed, the reviewer(s) may ask you to complete additional design work, tests, or other changes before your pull request can be ultimately accepted. +## Development Setup + +### 1. Ruby + +[`rbenv`](https://github.com/rbenv/rbenv) is the recommended way to manage Ruby versions: + +```shell +# Finalize the rbenv install (should work with both bash & zsh) +~/.rbenv/bin/rbenv init +# And then run +eval "$(~/.rbenv/bin/rbenv init - bash)" +``` + +### 2. Clone the repository + +Test data lives in a submodule, so make sure to clone recursively: + +```shell +git clone --recurse-submodules git@github.com:mindee/mindee-api-ruby.git ~/work/mindee/mindee-api-ruby +cd ~/work/mindee/mindee-api-ruby +``` + +If you already cloned without `--recurse-submodules`, run `git submodule update --init --recursive`. + +### 3. Install dependencies + +On Debian/Ubuntu: + +```shell +sudo apt install zlib1g-dev libssl-dev libreadline-dev libedit-dev libyaml-dev imagemagick +``` + +`imagemagick` is required at runtime by `mini_magick`, the rest are needed to build Ruby itself. + +```shell +# Ruby 3.3.0 is the minimum version supported by the SDK +rbenv install 3.3.0 +rbenv global 3.3.0 +``` + +### 4. Install code dependencies + +```shell +bundle config set --local path vendor +bundle install +``` + +### 5. Validate the install works by running unit tests + +```shell +bundle exec rake spec +``` + +## Local Quality Checks + +We use [`overcommit`](https://github.com/sds/overcommit) to run quality and security checks before +changes are committed and pushed. It is a development dependency of the gem, so `bundle install` +already installed it. The hooks are configured in [`.overcommit.yml`](.overcommit.yml), and +repository-local custom hooks live in [`.git-hooks`](.git-hooks). + +The same checks run in CI, see +[`.github/workflows/_static-analysis.yml`](.github/workflows/_static-analysis.yml). + +### Install `gitleaks` + +The `Gitleaks` pre-commit hook shells out to the +[`gitleaks`](https://github.com/gitleaks/gitleaks) binary, which is not a gem and must be installed +separately: + +```shell +brew install gitleaks +``` + +Otherwise, grab a binary from the +[releases page](https://github.com/gitleaks/gitleaks/releases) and put it on your `PATH`. + +### Install the hooks + +Run this once, after cloning: + +```shell +bundle exec overcommit --install +bundle exec overcommit --sign +bundle exec overcommit --sign pre-commit +``` + +`--install` writes the git hook stubs into `.git/hooks`, and the `--sign` calls tell overcommit you +trust the current contents of `.overcommit.yml` and of the custom hooks in `.git-hooks`. + +### What runs, and when + +* **pre-commit:** merge conflict markers, YAML syntax, trailing whitespace, file size, `rubocop`, + `steep check` (type checking) and `gitleaks` (secret scanning). +* **pre-push:** `bundle-audit` (dependency vulnerability check). + +### Run the hooks manually + +```shell +bundle exec overcommit --list-hooks # show which hooks are enabled +bundle exec overcommit --run # run the pre-commit hooks on all tracked files +bundle exec overcommit --run pre_push # run the pre-push hooks +bundle exec overcommit --diff main # run the pre-commit hooks on the diff against main +``` + +### Skipping hooks + +Skip one or more hooks for a single run, by name: + +```shell +SKIP=Gitleaks,Steep git commit +``` + +To bypass overcommit entirely (please use sparingly, CI runs the same checks): + +```shell +OVERCOMMIT_DISABLE=1 git commit +``` + +### Troubleshooting + +If overcommit refuses to run and warns that the configuration or the hooks have changed, review the +diff and then re-sign: + +```shell +bundle exec overcommit --sign +bundle exec overcommit --sign pre-commit +``` + ## Styleguides ### Git Commit Messages