fix: add necessary permissions to example workflow

[corneliusroemer]

trafficstars

Why:

Closes #31321

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

Uses the diff from https://github.com/github/docs/pull/31322/ but adds explicit permissions as well which allows it to be tested with workflow_dispatch: if users desire so

Also use github.ref_name instead of the pull_request.number to query the branch I couldn't get the original to work in local tests but with ref_name it works flawlessly.

Check off the following:

• [ ] I have reviewed my changes in staging, available via the View deployment link in this PR's timeline (this link will be available after opening the PR).

  • For content changes, you will also see an automatically generated comment with links directly to pages you've modified. The comment won't appear if your PR only edits files in the data directory.

• [ ] For content changes, I have completed the self-review checklist.

[github-actions[bot]]

Automatically generated comment ℹ️

This comment is automatically generated and will be overwritten every time changes are committed to this branch.

The table contains an overview of files in the content directory that have been changed in this pull request. It's provided to make it easy to review your changes on the staging site. Please note that changes to the data directory will not show up in this table.

---

Content directory changes

You may find it useful to copy this table into the pull request summary. There you can edit it to share links to important articles or changes and to give a high-level overview of how the changes in your pull request support the overall goals of the pull request.

Source	Preview	Production	What Changed
actions/using-workflows/caching-dependencies-to-speed-up-workflows.md	fpt ghec ghes@ 3.11 3.10 3.9 3.8	fpt ghec ghes@ 3.11 3.10 3.9 3.8

---

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

[nguyenalex836]

@corneliusroemer Thanks so much for opening a PR! I'll get this triaged for review ✨

[corneliusroemer]

@Mogyuchi made a good point that github.ref_name might not be the right name here, instead one should probably use github.head_ref.

[Mogyuchi]

@Mogyuchi made a good point that github.ref_name might not be the right name here, instead one should probably use github.head_ref.

@corneliusroemer Sorry, I should have just said it straight. In short, to clear the cache for a pull request, we need to stick to refs/pull/${{ github.event.pull_request.number }}/merge. Alternatively, if we want to clear the branch cache as well, we need to do it like discordjs-japan/om # 90 (pull_request should be replaced by pull_request_target).

[Mogyuchi]

…I feel like I need to explain how what is written in restrictions-for-accessing-a-cache affects cache cleanup. Simply put, for example, if you have a pull request 123 with head(current) branch feature-b, the cache created by the push event will be for feature-b and the cache created by the pull_request event will be for refs/pull/123 /merge. So, if the cache you want to delete was created in the push event, you need to specify the cache for feature-b, and if it was created in the pull_request event, you need to specify refs/pull/123/merge.

[jc-clark]

Hello @corneliusroemer and @Mogyuchi - thank you for the suggestions here. We had a chance to dig into this on our team and we agreed that we shouldn't change this example to use pull_request_target vs pull_request. The majority of our docs readers will be using the pull_request trigger and using this as the default aligns with the rest of our documentation as well.

That said, I didn't want to outright close this PR because I think it's a valid change to cover the cross-repository pull request use case.

In the "Events that trigger workflows" article, we do have a warning box about the permissions: "pull_request_target"

Which looks like it has the context someone would need for the cross-repo pull requests.

A few questions for you:

• What would you think of keeping pull_request as the triggering event here but adding a note above the example that links to "pull_request_target" and describes the cross-repo pull request use case?
• Based on this comment, it sounds like we should keep the permissions lines in this example even if we just use pull_request. Does that sound right?
• Should this line remain the same: BRANCH: refs/pull/{% raw %}${{ github.event.pull_request.number }}{% endraw %}/merge

[Mogyuchi]

@jc-clark

https://github.com/github/docs/pull/31582#discussion_r1486602743

Therefore, I believe it is more appropriate to make this a separate pull request from https://github.com/github/docs/pull/31322 .

What I wanted to say is that I don't want this pull request to be based on my pull request.

---

What would you think of keeping pull_request as the triggering event here but adding a note above the example that links to "pull_request_target" and describes the cross-repo pull request use case?

I think we should talk about this in https://github.com/github/docs/pull/31322, so I'll answer there.

Based on https://github.com/github/docs/pull/31582#discussion_r1486602743, it sounds like we should keep the permissions lines in this example even if we just use pull_request. Does that sound right?

Yes. We should specify the permission. https://securitylab.github.com/research/github-actions-building-blocks/#following-the-principle-of-least-privilege

Should this line remain the same: BRANCH: refs/pull/{% raw %}${{ github.event.pull_request.number }}{% endraw %}/merge

Yes. Related pull request: https://github.com/github/docs/pull/23612

[jc-clark]

Thanks for the additional context @Mogyuchi and @corneliusroemer. We're deciding to make some updates to this article internally to account for using the pull_request_target event.

Our engineers agreed that the example is good as is. So we are going to leave it using the default pull_request event and then add some information about using pull_request_target as an option.

I'm going to close out this PR and our team will merge some improvements to this article soon.