Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Update readme with additional examples and important note about pull_request_target event #721

Merged
merged 5 commits into from
Dec 18, 2023
Merged

Update readme with additional examples and important note about pull_request_target event #721

Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
2b36aaa
docs: add note about pull_request_target event trigger
Dec 15, 2023
02c5287
docs: change note from being caution to important
Dec 15, 2023
3e79d1d
docs: fix typos
Dec 15, 2023
239bb2e
docs: add examples to the examples chapter
Dec 15, 2023
752f0a9
docs: fix typos
Dec 15, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
39 changes: 36 additions & 3 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -13,6 +13,9 @@ Automatically label new pull requests based on the paths of files being changed

4) Version 5 of this action updated the [runtime to Node.js 20](https://docs.github.com/en/actions/creating-actions/metadata-syntax-for-github-actions#runs-for-javascript-actions). All scripts are now run with Node.js 20 instead of Node.js 16 and are affected by any breaking changes between Node.js 16 and 20.

> [!IMPORTANT]
> Before the update to the v5, please check out [this information](#notes-regarding-pull_request_target-event) about the `pull_request_target` event trigger.

## Usage

### Create `.github/labeler.yml`
Expand Down Expand Up @@ -110,6 +113,18 @@ Documentation:
- changed-files:
- any-glob-to-any-file: docs/*

# Add 'Documentation' label to any file changes within 'docs' or 'guides' folders
Documentation:
- changed-files:
- any-glob-to-any-file:
- docs/*
- guides/*

## Equivalent of the above mentioned configuration using another syntax
Documentation:
- changed-files:
- any-glob-to-any-file: ['docs/*', 'guides/*']

# Add 'Documentation' label to any change to .md files within the entire repository
Documentation:
- changed-files:
Expand All @@ -126,7 +141,7 @@ source:
feature:
- head-branch: ['^feature', 'feature']

# Add 'release' label to any PR that is opened against the `main` branch
# Add 'release' label to any PR that is opened against the `main` branch
release:
- base-branch: 'main'
```
Expand Down Expand Up @@ -246,9 +261,27 @@ jobs:
In order to add labels to pull requests, the GitHub labeler action requires write permissions on the pull-request. However, when the action runs on a pull request from a forked repository, GitHub only grants read access tokens for `pull_request` events, at most. If you encounter an `Error: HttpError: Resource not accessible by integration`, it's likely due to these permission constraints. To resolve this issue, you can modify the `on:` section of your workflow to use
[`pull_request_target`](https://docs.github.com/en/actions/using-workflows/events-that-trigger-workflows#pull_request_target) instead of `pull_request` (see example [above](#create-workflow)). This change allows the action to have write access, because `pull_request_target` alters the [context of the action](https://docs.github.com/en/actions/using-workflows/events-that-trigger-workflows#pull_request_target) and safely grants additional permissions. Refer to the [GitHub token permissions documentation](https://docs.github.com/en/actions/security-guides/automatic-token-authentication#permissions-for-the-github_token) for more details about access levels and event contexts.

## Notes regarding `pull_request_target`
## Notes regarding `pull_request_target` event

Using the `pull_request_target` event trigger involves several peculiarities related to initial set up of the labeler or updating version of the labeler.

### Initial set up of the labeler action

When submitting an initial pull request to a repository using the `pull_request_target` event, the labeler workflow will not run on that pull request because the `pull_request_target` execution runs off the base branch instead of the pull request's branch. Unfortunately this means the introduction of the labeler can not be verified during that pull request and it needs to be committed blindly.

### Updating major version of the labeler

When submitting a pull request that includes updates of the labeler action version and associated configuration files, using the `pull_request_target` event may result in a failed workflow. This is due to the nature of `pull_request_target`, which uses the code from the base branch rather than the branch linked to the pull request — so, potentially outdated configuration files may not be compatible with the updated labeler action.

To prevent this issue, you can switch to using the `pull_request` event temporarily, before merging. This event execution draws from the code within the branch of your pull request, allowing you to verify the new configuration's compatibility with the updated labeler action.

```yml
name: "Pull Request Labeler"
on:
- pull_request
```

When submitting a initial pull request to a repository using the `pull_request_target` event, the labeler workflow will not run on that pull request because the `pull_request_target` execution runs off the base branch instead of the pull request's branch. Unfortunately this means the introduction of the labeler can not be verified during that pull request and it needs to be committed blindly.
Once you confirm that the updated configuration files function as intended, you can then revert to using the `pull_request_target` event before merging the pull request. Following this step ensures that your workflow is robust and free from disruptions.

## Contributions

Expand Down