Document org-wide Warden scans

[sentry-junior]

Document a supported approach for running Warden across an entire GitHub org, not just individual repositories.

• cover an org-wide pattern such as using the orgName/.github repository to define shared scan configuration
• explain how org-wide scans should interact with per-repo scans and overrides
• include example configuration and operational guidance for enabling org-wide scanning safely

Action taken on behalf of David Cramer.

[dcramer]

Clarification on the desired org-wide model:

The org .github repository should define an org-wide Warden root, not just a shared workflow and not an automatic merge with repo-local config.

Example org repo layout:

.github/
├── .github/workflows/warden.yml
├── warden.toml
└── .agents/skills/
    └── security-review/
        ├── SKILL.md
        ├── references/
        └── scripts/

Desired behavior:

• The org-level ruleset-required workflow lives in org/.github.
• That workflow checks out the target repo for analysis.
• It also checks out org/.github into a stable directory such as .warden-org.
• Warden is invoked with an explicit config file in that checkout, e.g. .warden-org/warden.toml.
• dirname(config) should be treated as the Warden root for resolving bundled .agents/skills, references, scripts, and assets.
• Analysis paths and GitHub comments still refer to the target repository.
• Target repositories do not need any Warden files for the org-wide run to work.

Suggested action/API cleanup:

• Add an explicit config input that means an exact config file path.
• Deprecate or alias the current config-path input, which currently behaves indirectly by taking dirname(configPath) and loading warden.toml from there.

Example workflow invocation:

- uses: getsentry/warden@v0
  with:
    config: .warden-org/warden.toml

Repo-specific Warden config should not be automatically layered into the org-wide run. If a repository wants its own Warden configuration/run in addition to the org-wide one, it should define its own repo-local Warden workflow separately.

[dcramer]

Required Warden changes for this org-wide .github model:

1. Add an explicit config action input

   • Means an exact config file path, e.g. .warden-org/warden.toml.
   • Keep config-path as a compatibility alias or deprecate it.
   • Avoid the current indirect behavior where the action takes dirname(configPath) and always loads warden.toml.

2. Treat dirname(config) as the Warden root

   • Bare skill names in that config should resolve from that root.
   • Example: name = "security-review" in .warden-org/warden.toml should resolve .warden-org/.agents/skills/security-review.
   • Skill references, scripts, references, and assets should stay relative to the loaded skill root.
   • Analysis paths and GitHub comments must still be relative to the target repository checkout.

3. Support GitHub ruleset workflow events cleanly

   • GitHub ruleset workflows support pull_request, pull_request_target, and merge_group.
   • Warden already supports the PR path.
   • If we want the org-required workflow to include merge_group, Warden needs explicit merge_group event handling or a documented skip/pass behavior.

4. Do not automatically layer repo-local config

   • The org-wide run is defined by the org .github Warden root.
   • If a repository wants its own Warden run/config in addition, it should add its own repo-local workflow.

Acceptance criteria:

• A target repo with no Warden files can be analyzed using org/.github checked out to .warden-org.
• .warden-org/warden.toml can reference bundled skills by bare name.
• The action works with with: { config: ".warden-org/warden.toml" }.
• Existing repo-local config-path: warden.toml behavior remains compatible during migration.