Update README to document a few things

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