Create docs/pull_request_target.md

and link it in docs/add_pr_comment.md

See also #72

docs/add_pr_comment.md

@@ -2,7 +2,7 @@
 
 When a user proposes DNS configuration changes in a pull request, it may help to write the `octodns-sync` plan output to a comment in the pull request.
 
-This document describes two approaches for achieving this. Be aware that, for either approach, if users will propose DNS changes in pull requests **from forks** then it may be necessary to work around some GitHub token permission constraints.
+This document describes two approaches for achieving this. Be aware that, for either approach, if users will propose DNS changes in pull requests **from forks** then it may be necessary to work around some GitHub token permission constraints. See [pull_request_target.md] for more details.
 
 When using this Action's built-in `add_pr_comment` feature, be aware it'll add a new comment for each run. To avoid creating a new comment for each run, and/or to get more control over the contents of the comment, use @peter-evans' [`create-or-update-comment` Action] instead.
 
@@ -21,7 +21,7 @@ manager:
 
 ## Configure the workflow
 
-_Note: If users will propose DNS changes in pull requests **from forks** then it may be necessary to work around some GitHub token permission constraints._
+_Note: If users will propose DNS changes in pull requests **from forks** then it may be necessary to work around some GitHub token permission constraints. See [pull_request_target.md] for more details._
 
 ### @peter-evans' `create-or-update-comment` Action
 
@@ -100,5 +100,6 @@ jobs:
 Thank you @xt0rted @patcon @travislikestocode @thattommyhall for your help and support sorting :point_up: all this and improving **solvaholic/octodns-sync** :bow:
 
 
+[pull_request_target.md]: pull_request_target.md
 [`create-or-update-comment` Action]: https://github.com/peter-evans/create-or-update-comment
 [`plan_outputs` in the **octodns** configuration]: https://github.com/octodns/octodns/pull/156

docs/pull_request_target.md

@@ -0,0 +1,57 @@
+# Accepting pull requests from forks
+
+When accepting **octodns** configuration changes via pull requests from forks, it becomes appealing to trigger workflows on the [`pull_request_target` event]. This approach involves some complications - and some risks - it's important to know about beforehand.
+
+This document points out the risks and complications related to running the **solvaholic/octodns-sync** action, proposes ways to address them, and links to example configurations and relevant documentation.
+
+## Token permissions
+
+When a [GitHub Actions] workflow is triggered on the [`pull_request` event], the GitHub token the workflow receives will have [different permissions] depending on whether the pull request's head branch is local, or in a fork.
+
+For example, when the pull request's head is in a fork, a workflow triggered on `pull_request` will not have access to repository or environment [secrets]. This means it cannot use secrets to run `octodns-sync` and validate the proposed configuration change.
+
+Its GitHub token will also not have permission to add comments to pull requests.
+
+Work around these complications by triggering the workflow, instead, on the [`pull_request_target` event]. And consider these effects of doing so:
+
+- The workflow will run in the context of the pull request base, rather than its head.
+- Any user who can create a pull request can potentially access repository and environment secrets.
+
+## Running in the pull request base
+
+Workflows running in the context of the pull request head use the pull request merge commit as their [`github.ref`]. By default, they'll use the contributed code, as it would look if the pull request had already been merged.
+
+Workflows running in the context of the pull request base use that base as their [`github.ref`]. For example, `refs/heads/main`. By default, they'll use only the code that was already in the repository.
+
+So, when triggering workflows on the `pull_request_target` event, it's necessary to explicitly check out **octodns** configuration files from `refs/pull/NNN/merge` or `refs/pull/NNN/head`.
+
+## Protecting repository and environment secrets
+
+GitHub has already written this up, so it won't be repeated here. Read this post:
+
+[_Keeping your GitHub Actions and workflows secure: Preventing pwn requests_]
+
+If it doesn't feel relevant, or doesn't seem to address the concern related to **octodns** configuration repositories, set a reminder to read it again tomorrow.
+
+## Example workflows
+
+TODO
+
+## References and other examples
+
+[_Keeping your GitHub Actions and workflows secure: Preventing pwn requests_]
+
+[Example workflows](https://gist.github.com/xt0rted/a0ef1d3739cc333f8e3461532697d2ba) @xt0rted provided [in #41](https://github.com/solvaholic/octodns-sync/issues/58#issuecomment-835873880)
+
+## Thank you
+
+Thank you @xt0rted @patcon @travislikestocode for helping me understand this use case, and for improving **solvaholic/octodns-sync** :bow:
+
+
+[`pull_request_target` event]: https://docs.github.com/actions/reference/events-that-trigger-workflows#pull_request_target
+[`pull_request` event]: https://docs.github.com/actions/reference/events-that-trigger-workflows#pull_request
+[secrets]: https://docs.github.com/actions/reference/encrypted-secrets
+[different permissions]: https://docs.github.com/actions/reference/events-that-trigger-workflows#pull-request-events-for-forked-repositories
+[`github.ref`]: https://docs.github.com/actions/reference/context-and-expression-syntax-for-github-actions#github-context
+[GitHub Actions]: https://docs.github.com/actions/learn-github-actions/introduction-to-github-actions
+[_Keeping your GitHub Actions and workflows secure: Preventing pwn requests_]: https://securitylab.github.com/research/github-actions-preventing-pwn-requests/