Feature/secrets from forks guidance #17

[Vinodha-kumar]

Expand matrix with security-focused columns (fork PR, secrets, untrusted code execution, required gate/control).
Merge duplicated guidance into a single “Decision matrix and repository standard” section.
Clarify constraints for pull_request_target and environment-gated secret usage.

[AlexanderLanin]

Generated with Copilot running GPT-5.6 Terra

Thank you for taking on this gap. Guidance for handling secrets in fork PR workflows is valuable, and the security focus here gives contributors a strong starting point.

Suggested structure — split this by reader need. The current page mixes the explanation of the security model with two distinct operational tasks. Separating those parts will make the guidance easier to find and safer to apply:

1. Explanation: Put the background, threat model, trigger comparison, decision matrix, risks, and repository standard in the canonical automation narrative at docs/explanation/07-automation-integration.md (or in an explanation page linked from it). Explanation answers why the trust boundary exists and when each pattern is appropriate. Keeping this material only as a how-to would ask readers to configure a security-sensitive workflow before they understand the trade-offs.
2. How-to for module contributors: Add a short guide for the “simple user” of a repository: for example, “Run a secret-dependent verification for a fork PR.” It should describe the contributor-facing path for using the repository’s established protected check—complete ordinary unprivileged validation, satisfy the repository’s trust/approval process, and find or trigger the approved verification. It should not ask contributors to design workflows or manage secrets.
3. How-to for reusable action/workflow authors: Add a separate guide for maintainers who create reusable actions and workflows: for example, “Design a secret-dependent check for fork PRs.” It can give the concrete implementation sequence: keep pull_request validation secret-free; separate privileged work; configure the protected environment and required reviewers; apply minimal permissions and scoped secrets; and ensure untrusted code is never checked out or executed before the trust decision. This gives workflow authors an actionable implementation path without burdening module contributors with infrastructure details.

The two how-tos intentionally serve different audiences and should not be merged: contributors need to use an established safe path, while workflow authors need to implement that path. Keeping only the Explanation would leave both without instructions; keeping only one How-to would either overburden contributors or omit the authoring guidance.

This PR already contains most of the proposed Explanation content, so extracting the two focused procedures should keep the change manageable. Please add any standalone page to its section index and hidden toctree. The current page is not in docs/how-to/index.md, which makes the docs build fail with toc.not_included (warnings are errors).