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.

Resolves #17

[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).

[Copilot]

Pull request overview

Adds a new security-focused how-to guide to help maintainers choose safe GitHub Actions patterns for fork PRs and secrets, and links it into the documentation navigation.

Changes:

• Add a new guide covering pull_request vs pull_request_target vs environment-gated secret usage for fork PRs.
• Link the guide from the How-to toctree and from the repository README.

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 3 comments.

File	Description
README.md	Adds a “Security Guides” section linking to the new fork/secrets guide.
docs/how-to/index.md	Adds the new page to the how-to navigation toctree.
docs/how-to/github-actions-secrets-from-forks.md	New decision guide describing safe patterns and constraints for secrets with fork PR workflows.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[AlexanderLanin]

Oh that sounds like we have a problem here, but thats independent of this PR :D

For now please add the link into the how to section as its done for the other howtos

[AlexanderLanin]

Generated by Codex

Thanks for adding this important guidance—the safety boundaries are clearly stated. One content-focused suggestion: the page currently reads primarily as an Explanation (the threat model, option comparison, risks, and repository standard explain why and when to choose a pattern), while the How-to section should help a reader complete one concrete task.

Could you reshape it as follows?

1. Move the background, threat model, four-option discussion, decision matrix, and repository standard to the canonical automation explanation chapter (or a dedicated explanation page linked from it).
2. Make this How-to serve one named audience and goal—for example, “How to design a secret-dependent check for fork PRs.”
3. Replace the per-option narrative with an ordered procedure: keep ordinary validation on pull_request without secrets; split privileged work into a separate job; protect that job with a scoped environment and required reviewers; ensure the approved job does not check out or execute untrusted code before the trust decision; then verify the workflow with a fork PR.
4. Link back to the Explanation for the decision matrix and rationale, rather than duplicating them here.

That division would let maintainers quickly apply the safe pattern while keeping the reasoning and trade-offs easy to discover.

Thanks again!

— Codex