From 4d4da7ce8cd430cd3a826614515d95af14f042c7 Mon Sep 17 00:00:00 2001
From: Reuven Harrison <reuvenharrison@gmail.com>
Date: Fri, 8 May 2026 18:26:36 +0300
Subject: [PATCH] docs: document oasdiff.yaml support in free actions

The free actions (diff, breaking, changelog) are CLI wrappers; the
underlying CLI already looks up oasdiff.yaml from cwd, and GitHub
Actions sets the runner cwd to $GITHUB_WORKSPACE. So drop oasdiff.yaml
at the repo root and the actions pick it up automatically.

Adds a "Configuring with oasdiff.yaml" section under Free actions with
a runnable example, the precedence rule (action inputs override YAML),
and the boolean-only-enable-via-input limitation as a footnote.
---
 README.md | 19 +++++++++++++++++++
 1 file changed, 19 insertions(+)

diff --git a/README.md b/README.md
index d2988b0..f2eba4b 100644
--- a/README.md
+++ b/README.md
@@ -34,6 +34,25 @@ This compares your spec on the PR branch against the base branch and fails the w
 
 The following actions run the oasdiff CLI directly in your GitHub runner — no account or token required.
 
+### Configuring with `oasdiff.yaml`
+
+All free actions inherit the CLI's config-file support. Drop an `oasdiff.yaml` at your repo root and the actions pick it up automatically — no extra wiring needed:
+
+```yaml
+# oasdiff.yaml at your repo root
+exclude-elements:
+  - endpoints
+flatten-allof: true
+deprecation-days-stable: 180
+fail-on: ERR
+```
+
+Any flag the oasdiff CLI supports works in the config file — see [CONFIG-FILES.md](https://github.com/oasdiff/oasdiff/blob/main/docs/CONFIG-FILES.md) for the full reference and supported file formats (`oasdiff.{json,yaml,yml,toml,hcl}`).
+
+Action `inputs:` take precedence over config-file values, so you can use the file for shared defaults across workflows and override per-workflow via inputs.
+
+> **Limitation**: boolean flags can only be enabled through an action input. If your `oasdiff.yaml` sets `composed: true` and you want to disable it for a specific workflow run, edit the YAML — passing `composed: 'false'` in the action input has no effect.
+
 ### Check for breaking changes
 
 Detects breaking changes and writes inline GitHub annotations to the Actions summary. Fails the workflow when changes at or above the `fail-on` severity are found.