docs: security hardening info for actions untrusted content

[wrslatz]

Why:

The Security hardening for GitHub Actions documentation currently has no content or recommendations covering untrusted contents being checked out and executed in Actions workflow runs. Someone recently shared the Grafana GitHub Actions Security Incident write up from StepSecurity and I went to share the hardening guide with them only to not find any recommendations covering this case. I did share https://securitylab.github.com/research/github-actions-preventing-pwn-requests/ with them, but this was harder to find since it is not in the GitHub docs. I expected this security issue to be covered in the docs since untrusted input and third-party Actions, which have similar implications, are covered in the same docs already.

What's being changed (if available, include any code snippets, screenshots, or gifs):

Document the risks and recommended hardening mitigations for untrusted content being checked out and executed in GitHub Actions pull requests.

Check off the following:

• [ ] A subject matter expert (SME) has reviewed the technical accuracy of the content in this PR. In most cases, the author can be the SME. Open source contributions may require an SME review from GitHub staff.
• [ ] The changes in this PR meet the docs fundamentals that are required for all content.
• [ ] All CI checks are passing and the changes look good in the review environment.

[github-actions[bot]]

How to review these changes 👓

Thank you for your contribution. To review these changes, choose one of the following options:

• Spin up a codespace
• Set up a local development environment

A Hubber will need to deploy your changes internally to review.

Table of review links

Note: Please update the URL for your staging server or codespace.

The table shows the files in the content directory that were changed in this pull request. This helps you review your changes on a staging server. Changes to the data directory are not included in this table.

Source	Review	Production	What Changed
actions/reference/security/secure-use.md	fpt ghec ghes@ 3.17 3.16 3.15 3.14	fpt ghec ghes@ 3.17 3.16 3.15 3.14
actions/reference/workflows-and-actions/events-that-trigger-workflows.md	fpt ghec ghes@ 3.17 3.16 3.15 3.14	fpt ghec ghes@ 3.17 3.16 3.15 3.14
enterprise-onboarding/github-actions-for-your-enterprise/security-hardening-for-github-actions.md	ghec	ghec

Key: fpt: Free, Pro, Team; ghec: GitHub Enterprise Cloud; ghes: GitHub Enterprise Server

🤖 This comment is automatically generated.

[github-actions[bot]]

Thanks for opening a pull request! We've triaged this issue for technical review by a subject matter expert :eyes:

[github-actions[bot]]

This is a gentle bump for the docs team that this PR is waiting for technical review.

[Sharra-writes]

@wrslatz Sorry this took a while! I think I talked to most of the Actions teams before I found the one I needed to get the SME review. I'm referring it to our writers to review for style now. Thank you for being patient.

[wrslatz]

@wrslatz Sorry this took a while! I think I talked to most of the Actions teams before I found the one I needed to get the SME review. I'm referring it to our writers to review for style now. Thank you for being patient.

Thanks, @Sharra-writes !

[wrslatz]

I found an additional section of the docs that need an update related to this change. Pushing that up shortly.

[wrslatz]

@Sharra-writes @JarLob I found additional content in enterprise guidance that I updated in https://github.com/github/docs/pull/38048/commits/f4715110d9b2abe43cb76fa649fff6cf480e0336. Let me know what you think.

[dhianne92]

👍

On Fri, Jul 11, 2025, 02:56 Will Slattum @.***> wrote:

wrslatz left a comment (github/docs#38048) https://github.com/github/docs/pull/38048#issuecomment-3058577573

@Sharra-writes https://github.com/Sharra-writes @JarLob https://github.com/JarLob I found additional content in enterprise guidance that I updated in f471511 https://github.com/github/docs/commit/f4715110d9b2abe43cb76fa649fff6cf480e0336. Let me know what you think.

— Reply to this email directly, view it on GitHub https://github.com/github/docs/pull/38048#issuecomment-3058577573, or unsubscribe https://github.com/notifications/unsubscribe-auth/A7T2TZPSSREUCZ5JKWXPXP33H2ZPVAVCNFSM6AAAAAB4OWCPPGVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZTANJYGU3TONJXGM . You are receiving this because you are subscribed to this thread.Message ID: @.***>

[Sharra-writes]

@wrslatz We're doing some work on the organization of Actions articles, so the team asked me to put this on hold on our review board until that's finished, but hopefully that will give you time to get another review from the security folks, since the writing review needs to be the final thing once we know the information is correct.

[wrslatz]

@Sharra-writes Got security review 🎉 I can always rebase once those changes are in, just keep me posted.

[github-actions[bot]]

This is a gentle reminder for the docs team that this pull request is waiting for review.

[github-actions[bot]]

👋 Hey there spelunker. It looks like you've modified some files that we can't accept as contributions:

• src/audit-logs/data/fpt/organization.json
• src/audit-logs/data/fpt/user.json
• src/audit-logs/data/ghec/enterprise.json
• src/audit-logs/data/ghec/organization.json
• src/audit-logs/data/ghec/user.json
• src/audit-logs/data/ghes-3.14/enterprise.json
• src/audit-logs/data/ghes-3.14/organization.json
• src/audit-logs/data/ghes-3.14/user.json
• src/audit-logs/data/ghes-3.15/enterprise.json
• src/audit-logs/data/ghes-3.15/organization.json
• src/audit-logs/data/ghes-3.15/user.json
• src/audit-logs/data/ghes-3.16/enterprise.json
• src/audit-logs/data/ghes-3.16/organization.json
• src/audit-logs/data/ghes-3.16/user.json
• src/audit-logs/data/ghes-3.17/enterprise.json
• src/audit-logs/data/ghes-3.17/organization.json
• src/audit-logs/data/ghes-3.17/user.json
• src/audit-logs/data/ghes-3.18/enterprise.json
• src/audit-logs/data/ghes-3.18/organization.json
• src/audit-logs/data/ghes-3.18/user.json
• src/rest/data/ghec-2022-11-28/schema.json
• src/rest/data/ghes-3.14-2022-11-28/schema.json
• src/rest/data/ghes-3.16-2022-11-28/schema.json
• src/rest/data/ghes-3.17-2022-11-28/schema.json

You'll need to revert all of the files you changed that match that list using GitHub Desktop or git checkout origin/main <file name>. Once you get those files reverted, we can continue with the review process. :octocat:

The complete list of files we can't accept are:

• .devcontainer/**
• .github/**
• data/reusables/rai/**
• Dockerfile*
• src/**
• package*.json
• content/actions/how-tos/security-for-github-actions/security-hardening-your-deployments/**

We also can't accept contributions to files in the content directory with frontmatter type: rai or contentType: rai.

[github-actions[bot]]

👋 Hey there spelunker. It looks like you've modified some files that we can't accept as contributions:

• src/rest/data/ghec-2022-11-28/schema.json
• src/rest/data/ghes-3.16-2022-11-28/schema.json
• src/rest/data/ghes-3.17-2022-11-28/schema.json

You'll need to revert all of the files you changed that match that list using GitHub Desktop or git checkout origin/main <file name>. Once you get those files reverted, we can continue with the review process. :octocat:

The complete list of files we can't accept are:

• .devcontainer/**
• .github/**
• data/reusables/rai/**
• Dockerfile*
• src/**
• package*.json
• content/actions/how-tos/security-for-github-actions/security-hardening-your-deployments/**

We also can't accept contributions to files in the content directory with frontmatter type: rai or contentType: rai.

[wrslatz]

Oops, bad rebase to resolve conflicts. Let me fix that.

[wrslatz]

Okay, should be good now 🙏🏻 Not sure if the content updates discussed in https://github.com/github/docs/pull/38048#issuecomment-3070526113 have been done yet or not, but trying to keep the PR mergeable in case.

[Sharra-writes]

@wrslatz Sorry, I thought I marked this as ready for review yesterday, but it looks like I accidentally clicked "on hold" again. I believe the reorganization is finished, but the reviewer should be able to let you know if we need something changed.

[wrslatz]

@Sharra-writes Sorry for the ping 🙇🏻 Looks like there are check failures unrelated to my changes after syncing from the remote, and I'm not sure if that impacts the review status. Also not sure the status of review in general. Any guidance or info you can share is appreciated.

[Sharra-writes]

@wrslatz You can ping me with questions, it's fine. We were having some fun CI problems the last couple of days, but they should be resolved now (I hope so much that they're resolved now 😅). I know the review is taking a while - I've got a couple of things hanging out on the review board for this repository that haven't been picked up yet, so it's not just yours. The rest of the team is involved in an big reorganization of content trying to make things more sustainable as we keep adding docs, and it's summer so we have people on vacation, and one of the people who helps out in the open source repo a lot is sick.

I'll try to poke a bit next week to see if someone has time to get some open source reviews done, but I know everyone is pretty swamped. I'm sorry it's taking so long. You've been very patient and I appreciate it immensely.

[wrslatz]

@Sharra-writes 👋🏻 Wanted to make another friendly nudge here, given there was recently another supply chain attack caused by insecure use of untrusted content in an Actions workflow (see GHSA-cxm3-wv7p-598c). I'm hoping these docs would be useful for preventing and responding to future cases. I understand the delays with everything going on and summertime, though.

[Sharra-writes]

@wrslatz I've finally gotten someone looking at the PR in line before yours, though it's still not moving as quickly as I'd like it to. The writers rotate through being responsible for picking things up off the board weekly, though, so hopefully I can get the person in line next week to pick this one up. 🤞 It takes a while to get anything done, and I'm sorry about that.

[wrslatz]

Thank you! 🙏🏻

[Sharra-writes]

@wrslatz No guarantees that it will go faster than the other one that's being worked on, I'm just hoping really hard.

[wrslatz]

@Sharra-writes thanks for pushing all the fixes here :heart:

[Sharra-writes]

@wrslatz No problem! We're preparing this for review and my teammate wants to coach me through it. Writing isn't my primary job in this position, but it would be useful if I could pick up more reviews.

[Sharra-writes]

@wrslatz Hey, so, my teammate advised massively cutting down the warnings, because our experience with documentation tells us that people don't properly read long warnings and sometimes miss the DO NOT DO THIS we want them to see.

I picked out what I thought was the punchiest and most expressive sentence from the warnings, but this isn't my area of expertise. Do you think the sentence I picked represents the primary threat we're trying to warn against, or would you choose a different one/word it differently for better accuracy?

[wrslatz]

@wrslatz Hey, so, my teammate advised massively cutting down the warnings, because our experience with documentation tells us that people don't properly read long warnings and sometimes miss the DO NOT DO THIS we want them to see.

I picked out what I thought was the punchiest and most expressive sentence from the warnings, but this isn't my area of expertise. Do you think the sentence I picked represents the primary threat we're trying to warn against, or would you choose a different one/word it differently for better accuracy?

@Sharra-writes I did a quick scan and I think this still looks good and meets the objective while linking to specific details. I'll defer to security experts whether it provides sufficient guidance while remaining brief. The main question I have is how important it is to call out the specific permissions granted (write) and access risks (reading secrets) to understand the potential impact.

[Sharra-writes]

@wrslatz I got the go-ahead on this, so I'm going to get it added to the merge queue. You've been wonderful to work with. Thank you so much for your patience and for this great content. 💛

[github-actions[bot]]

Thanks very much for contributing! Your pull request has been merged 🎉 You should see your changes appear on the site in approximately 24 hours. If you're looking for your next contribution, check out our help wanted issues :zap:

[wrslatz]

Thanks y'all!

[uchitwai]

Read the Docs configuration file

See https://docs.readthedocs.io/en/stable/config-file/v2.html for details

Required

version: 2

Set the OS, Python version, and other tools you might need

build: os: ubuntu-24.04 tools: python: "3.13"

Build documentation in the "docs/" directory with Sphinx

sphinx: configuration: docs/conf.py

Optionally, but recommended,

declare the Python requirements required to build your documentation

See https://docs.readthedocs.io/en/stable/guides/reproducible-builds.html

python:

install:

- requirements: docs/requirements.txt