Fix and provide clarity on access token scopes needed (#314)
diff --git a/packages/github/README.md b/packages/github/README.md
index b1eae9b..b0b9ad7 100644
--- a/packages/github/README.md
+++ b/packages/github/README.md
@@ -36,16 +36,19 @@
- `username`: The user name of the GitHub repository.
- `repository`: The GitHub repository.
-- `accessToken`: Your GitHub personal access token. When you [create your token](https://github.com/settings/tokens), be sure to select the repo:status and public_repo scopes. Also, make sure that you don't have any webhooks already defined for your repository.
+- `accessToken`: Your GitHub personal access token.
- `events`: The [GitHub event type](https://developer.github.com/v3/activity/events/types/) of interest.
The following is an example of creating a trigger that will be fired each time that there is a new commit to a GitHub repository.
1. Generate a GitHub [personal access token](https://github.com/settings/tokens).
- The access token will be used in the next step.
+ - **Important** _When [creating your personal access token](https://help.github.com/en/github/authenticating-to-github/creating-a-personal-access-token-for-the-command-line), be sure to select the following **scopes**:_
+ - **repo**: **repo:status** to allow access to commit status.
+ - **admin:repo_hook**: **write:repo_hook** to allow the feed action to create your webhook.
+ - **Warning** _Make sure that you don't have any webhooks already defined for your repository or they may be overwritten._
-2. Create a package binding that is configured for your GitHub repository and with your access token.
+2. Create a package binding that is configured for your GitHub repository and with the personal access token created in step 1.
```
wsk package bind /whisk.system/github myGit \
@@ -61,5 +64,7 @@
```
A commit to the GitHub repository by using a `git push` causes the trigger to be fired by the webhook. If there is a rule that matches the trigger, then the associated action will be invoked.
+
The action receives the GitHub webhook payload as an input parameter. Each GitHub webhook event has a similar JSON schema, but is a unique payload object that is determined by its event type.
+
For more information about the payload content, see the [GitHub events and payload](https://developer.github.com/v3/activity/events/types/) API documentation.
