From 86843fdbb59b8b529c814a0d7dbca8acdda3516f Mon Sep 17 00:00:00 2001
From: Yoann Chaudet <yoannchaudet@github.com>
Date: Tue, 26 Jul 2022 10:47:31 -0700
Subject: [PATCH] Update README to document a few things

---
 README.md | 68 +++++++++++++++++++++++++++++++++++++++++++++++++------
 1 file changed, 61 insertions(+), 7 deletions(-)

diff --git a/README.md b/README.md
index 37b40db..6521143 100644
--- a/README.md
+++ b/README.md
@@ -1,17 +1,71 @@
 # Deploy-Pages
 
-This deploys artifacts to GitHub Pages.
+This action is used to deploy [Actions artifacts][artifacts] to GitHub Pages.
 
-# Scope
+## Scope
 
-⚠️ Official support for building Pages with Actions is in public beta at the moment. The scope is currently limited to **public repositories only**.
+⚠️ Official support for building Pages with Actions is in public beta at the moment.
 
-# Usage
+## Usage
 
-See [action.yml](action.yml)
+See [action.yml](action.yml) for the various `inputs` this action supports.
 
-<!-- TODO: document custom workflow -->
+To see real workflows making use of this action, see the [Pages starter-workflows][starter-workflows] that we publish.
 
-# License
+This action expects an artifact to have been uploaded from the same workflow using [`actions/upload-pages-artifact`][upload-pages-artifact].
+
+We recommend this action to be used in a dedicated job:
+
+```yaml
+jobs:
+  # Build job
+  build:
+    # <Not provided for brevity>
+    # At a minimum this job should upload artifacts using actions/upload-pages-artifact
+
+  # Deploy job
+  deploy:
+    # Add a dependency to the build job
+    needs: build
+
+    # Grant GITHUB_TOKEN the permissions required to make a Pages deployment
+    permissions:
+      pages: write      # to deploy to Pages
+      id-token: write   # to verify the deployment originates from an appropriate source
+
+    # Deploy to the github-pages environment
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+
+    # Specify runner + deployment step
+    runs-on: ubuntu-latest
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v1
+```
+
+# Security considerations
+
+There are a few important considerations to be aware of:
+
+1. The artifact being deployed must have been uploaded in the same workflow (it can originates from a different job though)
+
+2. The deployment step must at minimum have the following permissions:
+   - `pages: write`
+   - `id-token: write`
+
+3. The deployment must target a `github-pages` environment (you may use a different environment name but we don't recommend it)
+
+4. If your Pages site is using a source branch, the deployment must originate from this source branch unless [your environment is protected][environment-protection] in which case the environment protection rules take precedence over the source branch rule
+
+## License
 
 The scripts and documentation in this project are released under the [MIT License](LICENSE).
+
+<!-- references -->
+[starter-workflows]: https://github.com/actions/starter-workflows/tree/main/pages
+[upload-pages-artifact]: https://github.com/actions/upload-pages-artifact
+[artifacts]: https://docs.github.com/en/actions/using-workflows/storing-workflow-data-as-artifacts
+[environment-protection]: https://docs.github.com/en/actions/deployment/targeting-different-environments/using-environments-for-deployment#environment-protection-rules
\ No newline at end of file