github secrets from forks

[AlexanderLanin]

We need to run workflows which have access to secrets. This is currently not possible.

Two common ways to achieve that is using pull_request_target instead of pull_request and the other is using environments.

Acceptance Criteria:

• Provide guide when to use which approach
• Focus on constraints and security implications (e.g., risks of running untrusted code with access to secrets)

[FScholPer]

I would love environments

[AlexanderLanin]

Hints for issue:

• environments require per-PR approval, so they are not suitable for "the big mass of PRs"
• Our pull_request_target workflows currently do not pre-merge PRs before running checks. Checks that run on pull_request are pre-merged. This difference currently leads to some subtle pull request or post merge failures.
• It does seem very insecure to use pull_request_target and then run arbitrary code from PRs
• stupid idea at the moment is to run pull_request_target for contributors, and environments for the public.
• further investigation required!

[AlexanderLanin]

Reminder: workflows that start from forks do not have write permissions. That's especially relevant for gh-pages.

[AlexanderLanin]

Designing GitHub Workflows With Secrets: Trust Boundaries and Safe Patterns

Status: awaiting review and feedback by GitHub Actions / Secret / Fork experts

1. Core Principle: Fork PRs Are Always Untrusted

GitHub enforces a (surprisingly meaningful) strict security model for external pull requests:

• Fork PRs are always untrusted, regardless of contributor identity
• PRs cannot access secrets, environments, or write-scoped GITHUB_TOKENs
• Any step executing PR-supplied code (builds, tests, scripts) must assume arbitrary code execution
• Secret usage must never depend on “being careful”; it must depend on platform enforcement

“Since, by definition, a PR supplies code to any build or test logic in place for your project, attackers can achieve arbitrary code execution.” — GitHub Security Lab

---

2. Workflow Design Overview

Different models offer different trade-offs between convenience and safety:

Model	Trust Split	Platform-Enforced Boundary	Suitable For	Notes
0) pull_request	100–0	✔️ Yes	Standard CI (lint, unit tests, builds)	Safest, no secrets
1) Two-workflow (A→B)	90–10	✔️ Yes	Trusted post-processing based on artifacts	Strong isolation
2) Two-workflow + Environment	50–50	✔️ Yes + ✔️ Human approval	tbd	Every PR requires manual approval
3) pull_request_target	—	❌ No	❌ No	❌ Fragile security by convention
4) pull_request_target + Environment	0–100	✔️ Human approval	Running PR code with licensed tools	Every PR requires manual approval

---

3. In Detail

Option 1 — Two-Workflow Model (pull_request → workflow_run)

Use when: Only post-processing needs access to secrets.

Workflow A (pull_request)

• Runs untrusted PR code
• No secrets
• Builds/tests and uploads artifacts

Workflow B (workflow_run)

• Runs from main
• Has secrets
• Uses only trusted workflow logic
• Consumes artifacts from A, e.g. for publishing, PR comments, etc
• Never executes PR code directly

Security Properties

• Platform enforces a hard separation
• Even accidental misuse cannot leak secrets
• PRs cannot influence trusted workflow logic

---

Option 2 — Two-Workflow Model + Protected Environment

Use when: You can run parts of your job in untrusted context, but some parts need to run reviewed PR code in a trusted context.

Examples: integration tests, licensed tools, hardware access.

Setup

• Workflow B requires environment approval before secrets are exposed
• Maintainers review the PR and workflow artifacts
• Only afterward can B run PR code

Benefits

• Strong separation still enforced by workflows A/B
• Human approval prevents accidental execution of malicious code

---

Option 3 — pull_request_target without Environment

Never use for fork-based CI that touches secrets.

Reasons:

• Runs in a fully trusted context
• Secrets and elevated permissions are available by default
• A single misconfigured checkout leaks secrets
• No platform boundary; safety depends entirely on YAML discipline

“What about two jobs in one workflow?”

Sometimes attempted (e.g. docs-as-code):

• Job 1: “Untrusted” logic
• Job 2: “Trusted” logic

But:

1. Both jobs execute in a trusted workflow, regardless of intent
2. A checkout mistake in Job 2 compromises secrets
3. PRs cannot modify workflow logic, so workflow edits cannot be tested safely

This is only a simulation of separation — not true isolation.

---

Option 4 — pull_request_target + Environment (The 0–100 Split)

Use when:

• The privileged run must execute PR code, without meaningful preparation in untrusted context
• Only selected isolated secrets are involved (e.g., a license key)
• A maintainer manually approves every run

This model is appropriate when the valuable resource is the licensed tool, not additional secrets.

Example: Running PR code with a licensed compiler that cannot be exposed in untrusted workflows.

Still, there is no workflow-level isolation, so treat this as an exception.

---

5. Open Questions

• Can secrets be enabled only for “trusted contributors”? e.g. clever combinations ob the above options for committers working from a fork.

---

6. Practical Recommendations

• Use pull_request_target + environment as a simple setup for licensed compilers
• Prefer two-workflow designs whenever secrets are involved
• Use environment approval for any workflow that evaluates untrusted code

---

7. References

• https://docs.github.com/actions/using-workflows/events-that-trigger-workflows#pull_request_target
• https://docs.github.com/actions/security-guides/security-hardening-for-github-actions#using-workflow_run-events-to-build-a-defense-in-depth-strategy
• https://securitylab.github.com/resources/github-actions-preventing-pwn-requests/