Skip to content

Documentation Update - add permissions section to readme #511

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

Open
wants to merge 1 commit into
base: main
Choose a base branch
from
Open

Documentation Update - add permissions section to readme #511

Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
20 changes: 20 additions & 0 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -132,6 +132,26 @@ By default, the following status codes will not be retried: `400, 401, 403, 404,

These retries are implemented using the [octokit/plugin-retry.js](https://github.com/octokit/plugin-retry.js) plugin. The retries use [exponential backoff](https://en.wikipedia.org/wiki/Exponential_backoff) to space out retries. ([source](https://github.com/octokit/plugin-retry.js/blob/9a2443746c350b3beedec35cf26e197ea318a261/src/error-request.ts#L13))

## Recommended Permissions

The permissions required for the `GITHUB_TOKEN` in your workflow vary depending on how you use `github-script`. To ensure secure and efficient use of this action, we recommend reviewing and setting the least privileges necessary for your use case.

### Determine the Required Permissions

1. **`GITHUB_TOKEN` Authentication**
GitHub automatically provides a `GITHUB_TOKEN` for workflows. You can customize the permissions granted to this token. Refer to the documentation for details:
[Permissions for the `GITHUB_TOKEN`](https://docs.github.com/en/actions/security-for-github-actions/security-guides/automatic-token-authentication#permissions-for-the-github_token)

2. **API Calls with Installation Access Tokens**
If you're using `github-script` to make API calls requiring installation access tokens, ensure the permissions are configured appropriately for those endpoints. Learn more here:
[Permissions for installation access tokens](https://docs.github.com/en/rest/authentication/endpoints-available-for-github-app-installation-access-tokens)
Comment on lines +135 to +147
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think we can simplify this a bit

Suggested change
## Recommended Permissions
The permissions required for the `GITHUB_TOKEN` in your workflow vary depending on how you use `github-script`. To ensure secure and efficient use of this action, we recommend reviewing and setting the least privileges necessary for your use case.
### Determine the Required Permissions
1. **`GITHUB_TOKEN` Authentication**
GitHub automatically provides a `GITHUB_TOKEN` for workflows. You can customize the permissions granted to this token. Refer to the documentation for details:
[Permissions for the `GITHUB_TOKEN`](https://docs.github.com/en/actions/security-for-github-actions/security-guides/automatic-token-authentication#permissions-for-the-github_token)
2. **API Calls with Installation Access Tokens**
If you're using `github-script` to make API calls requiring installation access tokens, ensure the permissions are configured appropriately for those endpoints. Learn more here:
[Permissions for installation access tokens](https://docs.github.com/en/rest/authentication/endpoints-available-for-github-app-installation-access-tokens)
## Recommended permissions
The permissions required for the `GITHUB_TOKEN` in your workflow vary depending on how you use `actions/github-script`. We recommend reviewing and setting the least privileges necessary for your use case.
See [Permissions for the `GITHUB_TOKEN`](https://docs.github.com/actions/security-for-github-actions/security-guides/automatic-token-authentication#permissions-for-the-github_token) for details on the available permissions and [Permissions for installation access tokens](https://docs.github.com/en/rest/authentication/endpoints-available-for-github-app-installation-access-tokens) for information on what permissions each API requires.


### General Best Practices

- Use the principle of least privilege: Only grant the specific permissions needed for your workflow.
- Regularly audit and review your workflows to ensure permissions remain appropriate for your use cases.
- Test your workflows with the intended permissions to verify they work as expected without over-permissioning.
Comment on lines +149 to +153
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'd remove this section personally - this would be betters suited in our GitHub documentation for Actions best practices rather than in this action's README.


## Examples

Note that `github-token` is optional in this action, and the input is there
Expand Down
Loading