{"meta":{"title":"Uso seguro de pull_request_target","intro":"Saiba mais sobre os riscos de segurança do pull_request_target event.","product":"GitHub Actions","breadcrumbs":[{"href":"/pt/actions","title":"GitHub Actions"},{"href":"/pt/actions/reference","title":"Referência"},{"href":"/pt/actions/reference/security","title":"Segurança"},{"href":"/pt/actions/reference/security/securely-using-pull_request_target","title":"Uso seguro de pull_request_target"}],"documentType":"article"},"body":"# Uso seguro de pull_request_target\n\nSaiba mais sobre os riscos de segurança do pull_request_target event.\n\n<!-- TRANSLATION_FALLBACK prop=markdown type=ParseError line=73 col=1 msg=\"tag {% ifversion fpt or ghec %} not closed\" -->\nThis guide helps you assess whether your workflow should use the `pull_request_target` event and understand the security risks involved. It also explains the protection GitHub applies to [`actions/checkout`](https://github.com/actions/checkout) v7 and later to reduce these risks by default, and when to opt out of that protection if necessary.\n\nRead [`pull_request_target`](/en/actions/reference/workflows-and-actions/events-that-trigger-workflows#pull_request_target) before you check out pull request code from one of these workflows, or before you set the `allow-unsafe-pr-checkout` input on `actions/checkout`.\n\n## The risks of the pull\\_request\\_target event\n\nWorkflows triggered by `pull_request_target` run with elevated trust: the job receives the base repository's `GITHUB_TOKEN` and access to repository and organization secrets. This is the same trust given to events like `push` that only collaborators can trigger, and it is what makes `pull_request_target` useful for automation that responds to pull requests from forks, such as labeling, triage, or for posting authenticated status checks.\n\nTo understand why this is safe by default, and how that safety is commonly broken, review `pull_request_target` against [`pull_request`](/en/actions/reference/workflows-and-actions/events-that-trigger-workflows#pull_request).\n\nThe `pull_request` event (along with `pull_request_review` and `pull_request_review_comment`) is unusual: it runs the workflow file from the **merge commit of the pull request**. For a pull request opened from a fork, that commit is controlled by someone without write access to the base repository. To run untrusted workflow code safely, GitHub restricts these events to a read-only `GITHUB_TOKEN`, withholds access to other secrets, and applies fork approval policies to prevent compute abuse. For more information, see [Events that trigger workflows](/en/actions/reference/workflows-and-actions/events-that-trigger-workflows#pull_request). By default, `actions/checkout` in a `pull_request` workflow also checks out the pull request's merge commit, so the code checked out and the workflow that runs are consistent.\n\n`pull_request_target` makes one critical and subtle change: the workflow, and any subsequent `actions/checkout` call that does not specify a `ref`, is taken from the **base repository's default branch**, not from the pull request. Because only trusted code from the default branch runs, it is safe to grant secrets and a read/write token. No code from the fork is executed by default.\n\nYou introduce risk when a workflow author overrides this default to run the fork's code. Developers frequently choose `pull_request_target` because they want to run a fork's pull request through CI *and* have access to secrets, for example to run tests that need a private registry. To do this, they point `actions/checkout` at the pull request head instead of the default branch, which is insecure:\n\n```yaml\n# INSECURE. Provided as an example only.\non:\n  pull_request_target:\n\njobs:\n  build:\n    runs-on: ubuntu-latest\n    steps:\n      - uses: actions/checkout@v6\n        with:\n          ref: ${{ github.event.pull_request.head.sha }}\n      - name: Test\n        run: make test\n```\n\nThe checkout step alone does not execute untrusted code. The workflow file itself still comes from the default branch. The vulnerability is completed by the *next* step that runs code checked out into the current working directory. Here, `make test` executes a `Makefile` taken from the pull request head. An attacker only needs to open a pull request from a fork whose `Makefile` (or build script, test command, dependency, or configuration file) contains malicious commands. Those commands then run with the base repository's secrets and token.\n\nThis pattern is known as a \"pwn request\" and has been the root cause of multiple supply-chain compromises. For more information, see [Preventing pwn requests](https://securitylab.github.com/resources/github-actions-preventing-pwn-requests/) from the GitHub Security Lab. Common vulnerable shapes include:\n\n* Checking out a pull request's head or merge commit in `actions/checkout` (`ref: ${{ github.event.pull_request.head.sha }}`, `ref: refs/pull/${{ github.event.pull_request.number }}/merge`) and then building, testing, or otherwise executing the result.\n* Setting `repository:` to the fork (`repository: ${{ github.event.pull_request.head.repo.full_name }}`) to pull the fork's branch directly.\n* Fetching the pull request code outside of `actions/checkout` (for example with `git fetch`, `gh pr checkout`, or by downloading an artifact from a fork's `pull_request` run) and then running it.\n\nPwn requests are also not unique to `pull_request_target`. Any event that runs with secrets can introduce a pwn request if it checks out or downloads and executes untrusted code. For example, an `issue_comment` or `workflow_run` workflow that fetches and runs a fork's pull request code is vulnerable in the same way. A `workflow_run` workflow should treat artifacts uploaded by other workflows as untrusted data, since their contents can come from a fork.\n\n## Deciding whether to use pull\\_request\\_target\n\nSome workflows need to check out fork pull request code with elevated trust, and this is why `pull_request_target` was created in the first place. For example, generating coverage reports that require a private artifact registry or producing and running authenticated checks against the changes introduced from the pull request. Consider the questions below before using `pull_request_target` or opting into the `allow-unsafe-pr-checkout` flag in `actions/checkout`.\n\n* **Can you use `pull_request` instead?** `pull_request` triggers on the same events as `pull_request_target` and runs the workflow code from the `pull_request` merge branch. It does this safely on pull requests from forks with the protections detailed above. If additional secret access is not needed, use `pull_request`. More complex workflows can be restructured to separate potentially dangerous handling of pull request code from accessing secrets. For more information, see [Preventing pwn requests](https://securitylab.github.com/resources/github-actions-preventing-pwn-requests/#preventing-pwn-requests) from the GitHub Security Lab.\n\n* **Is the checked-out code ever executed?** This is the flaw that introduces pwn request vulnerabilities. It is most commonly introduced with `actions/checkout` by checking out a pull request head into the working directory and then running it. Unless the `path` input is set, `actions/checkout` writes the code into the `$GITHUB_WORKSPACE` directory, which is typically the working directory where subsequent commands run. Execution is not limited to your own steps: build and test commands such as `npm install` and `npm run build`, as well as configuration files and dependencies the code brings with it, can all run attacker-controlled code. Execution does not require an obvious build step. **You must ensure the checked-out code is only ever inspected as data and never executed before using a `pull_request_target` event**.\n\n## Hardening a pull\\_request\\_target workflow\n\nIf you have confirmed you need `pull_request_target`, apply these controls to limit the impact of this high-risk event. These apply whether or not your workflow checks out pull request code.\n\n* **Restrict secrets.** Confirm that the permissions set on the `GITHUB_TOKEN` have the least privileges and that only the necessary repository and organization secrets are used for the workflow. For more information, see [Use GITHUB\\_TOKEN for authentication in workflows](/en/actions/tutorials/authenticate-with-github_token#modifying-the-permissions-for-the-github_token).\n\n* **Understand the impact to caching.** To reduce the risk of cache poisoning, workflows triggered by `pull_request_target` have read-only access to the cache in the default branch's scope. These workflows can restore existing cache entries but cannot create or overwrite them, so they cannot affect the execution of other, unrelated, workflows through the shared cache. If such a workflow attempts to save a cache, the save fails but the step and the job continue, and the failure is reported as a warning in the workflow log. If your workflow needs to populate the cache, save it from a workflow that runs on a trusted trigger such as `push`. For more information, see [Dependency caching reference](/en/actions/reference/workflows-and-actions/dependency-caching#cache-access-for-low-trust-workflow-triggers).\n\n* **Ensure the underlying compute is isolated and ephemeral.** If self-hosted runners are used, you must confirm that the runner environment is properly restricted from internal resources and is not reused across GitHub Actions runs. For more information, see [Secure use reference](/en/actions/reference/security/secure-use#hardening-for-self-hosted-runners).\n\n* **Enforce GitHub Actions security best practices.** In addition to the specific risks of pwn requests, other common vulnerabilities, such as command injection, can exist and impact the code executed in this privileged event. For more information, see [Keeping your GitHub Actions and workflows secure: Untrusted input](https://securitylab.github.com/resources/github-actions-untrusted-input/) from the GitHub Security Lab. To identify and proactively protect against common GitHub Actions vulnerabilities, enable CodeQL for GitHub Actions. For more information, see [Configuring default setup for code scanning](/en/code-security/how-tos/find-and-fix-code-vulnerabilities/configure-code-scanning/configure-code-scanning).\n\n## Opting out of built-in protections\n\nIf you have worked through the questions above and confirmed your workflow requires `pull_request_target` and uses it safely, you can opt out of the `actions/checkout` protection. Setting `allow-unsafe-pr-checkout: true` as an `actions/checkout` input allows checking out pull request head refs from forks. Only do this after confirming the checked-out code is never executed. The input is intentionally named to be easy to spot in code review and static analysis.\n\nThis protection only covers fork pull request refs. Checking out other untrusted code, such as an unrelated third-party repository, fetching code with `git fetch` or `gh pr checkout`, or running a downloaded artifact, is not covered by the `actions/checkout` checks.\n\n## Restricting the use of pull\\_request\\_target\n\nIf a repository has no legitimate use for `pull_request_target`, restricting the event removes the risk regardless of how individual workflows are written. Administrators can use workflow execution protections to control which events and actors can trigger workflows. For more information, see the workflow execution protections documentation for repositories ([Workflow execution protections](/en/repositories/managing-your-repositorys-settings-and-features/actions-policies/workflow-execution-protections)) and organizations ([Workflow execution protections](/en/organizations/managing-organization-settings/actions-policies/workflow-execution-protections))."}