From 3cc9b29b076f6013768c2ddf1c3f1e587621d0ee Mon Sep 17 00:00:00 2001
From: Shaun Kirk Wong <skw@github.com>
Date: Thu, 24 Mar 2022 06:18:57 +0000
Subject: [PATCH] github/memex#8948: Adding docs for supported events, creating
 PATs and commit SHAs

---
 README.md | 63 +++++++++++++++++++++++++++++++++++++++++++++++++------
 1 file changed, 57 insertions(+), 6 deletions(-)

diff --git a/README.md b/README.md
index 22662c2..147cfda 100644
--- a/README.md
+++ b/README.md
@@ -14,6 +14,10 @@ experimentation until a release has been prepared.** 🚨
 
 ## Usage
 
+_See [action.yml](action.yml) for [metadata](https://docs.github.com/en/actions/creating-actions/metadata-syntax-for-github-actions) that defines the inputs, outputs, and runs configuration for this action._
+
+_For more information about workflows, see [Using workflows](https://docs.github.com/en/actions/using-workflows)._
+
 To use the action, create a workflow that runs when issues are opened in your
 repository. Run this action in a step, optionally configuring any filters you
 may want to add, such as only adding issues with certain labels.
@@ -31,9 +35,6 @@ jobs:
     name: Add issue to project
     runs-on: ubuntu-latest
     steps:
-      # Pointing to a branch name generally isn't the safest way to refer to an action,
-      # but this is how you can use this action now before we've begun creating releases.
-      # Another option would be to point to a full commit SHA.
       - uses: actions/add-to-project@main
         with:
           project-url: https://github.com/orgs/<orgName>/projects/<projectNumber>
@@ -43,14 +44,64 @@ jobs:
 
 ## Inputs
 
-- `project-url` is the URL of the GitHub Project to add issues to.
-- `github-token` is a [personal access
+- <a name="project-url">`project-url`</a> _(required)_ is the URL of the GitHub Project to add issues to.
+- <a name="github-token">`github-token`</a> _(required)_ is a [personal access
   token](https://github.com/settings/tokens/new) with the `repo`, `write:org` and
   `read:org` scopes.
-- `labeled` is a comma-separated list of labels. For an issue to be added to the
+  _See [Creating a PAT and adding it to your repository](creating-a-pat-and-adding-it-to-your-repository) for more details_
+- <a name="labeled">`labeled`</a> _(optional)_ is a comma-separated list of labels. For an issue to be added to the
   project, it must have _one_ of the labels in the list. Omitting this key means
   that all issues will be added.
 
+## Supported Events
+
+Currently this action supports the following [issue events](https://docs.github.com/en/actions/using-workflows/events-that-trigger-workflows#issues):
+
+- `opened`
+- `transferred`
+
+This ensures that all issues in the workflow's repo are added to the [specified project](#project-url). If [labeled input(s)](#labeled) are defined, then issues will only be added if they contain at least _one_ of the labels in the list.
+
+## How to point the action to a specific branch or commit sha
+
+Pointing to a branch name generally isn't the safest way to refer to an action, but this is how you can use this action now before we've begun creating releases.
+
+```yaml
+jobs:
+  add-to-project:
+    name: Add issue to project
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/add-to-project@main
+        with:
+          project-url: https://github.com/orgs/<orgName>/projects/<projectNumber>
+          github-token: ${{ secrets.ADD_TO_PROJECT_PAT }}
+```
+
+Another option would be to point to a full [commit SHA](https://docs.github.com/en/get-started/quickstart/github-glossary#commit):
+
+```yaml
+jobs:
+  add-to-project:
+    name: Add issue to project
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/add-to-project@<commitSHA>
+        with:
+          project-url: https://github.com/orgs/<orgName>/projects/<projectNumber>
+          github-token: ${{ secrets.ADD_TO_PROJECT_PAT }}
+```
+
+## Creating a PAT and adding it to your repository
+
+- create a new [personal access
+  token](https://github.com/settings/tokens/new) with `repo`, `write:org` and
+  `read:org` scopes
+  _see [Creating a personal access token](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token)_
+
+- add the newly created PAT as a repository secret, this secret will be referenced by the [github-token input](#github-token)
+  _see [Encrypted secrets](https://docs.github.com/en/actions/security-guides/encrypted-secrets#creating-encrypted-secrets-for-a-repository)_
+
 ## Development
 
 To get started contributing to this project, clone it and install dependencies.