From 86843fdbb59b8b529c814a0d7dbca8acdda3516f Mon Sep 17 00:00:00 2001 From: Yoann Chaudet Date: Tue, 26 Jul 2022 10:47:31 -0700 Subject: [PATCH 1/8] 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. - +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: + # + # 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). + + +[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 From 1f18c7a3bab746a1758b004a9ff374333276e7b5 Mon Sep 17 00:00:00 2001 From: Yoann Chaudet Date: Tue, 26 Jul 2022 11:09:31 -0700 Subject: [PATCH 2/8] Document default too --- README.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/README.md b/README.md index 6521143..55f57b5 100644 --- a/README.md +++ b/README.md @@ -60,6 +60,8 @@ There are a few important considerations to be aware of: 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 +5. If your Pages site is using GitHub Actions as the source, while not required we highly recommend you also [protect your environment][environment-protection] (we do it by default for you) + ## License The scripts and documentation in this project are released under the [MIT License](LICENSE). From 33bba0fd45d6b70ac57b3830e612bdc4c97dca16 Mon Sep 17 00:00:00 2001 From: Yoann Chaudet Date: Tue, 26 Jul 2022 11:10:56 -0700 Subject: [PATCH 3/8] Update README.md Co-authored-by: Tommy Byrd --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 55f57b5..27efcea 100644 --- a/README.md +++ b/README.md @@ -50,7 +50,7 @@ jobs: 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) +1. The artifact being deployed must have been uploaded in a previous step, either in the same job or a separate job that doesn't execute until the upload is complete. 2. The deployment step must at minimum have the following permissions: - `pages: write` From f5d172a5618a984b085fe781c1307ca6a4382373 Mon Sep 17 00:00:00 2001 From: Yoann Chaudet Date: Tue, 26 Jul 2022 11:11:16 -0700 Subject: [PATCH 4/8] Update README.md Co-authored-by: Tommy Byrd --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 27efcea..69bfce3 100644 --- a/README.md +++ b/README.md @@ -56,7 +56,7 @@ There are a few important considerations to be aware of: - `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) +3. The deployment should target the `github-pages` environment (you may use a different environment name if needed, but this is not recommended.) 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 From 974e2a6ded54e2ff8102b94f375f4aaf70f6b01b Mon Sep 17 00:00:00 2001 From: Yoann Chaudet Date: Tue, 26 Jul 2022 11:11:30 -0700 Subject: [PATCH 5/8] Update README.md Co-authored-by: Tommy Byrd --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 69bfce3..eba6df7 100644 --- a/README.md +++ b/README.md @@ -10,7 +10,7 @@ This action is used to deploy [Actions artifacts][artifacts] to GitHub Pages. See [action.yml](action.yml) for the various `inputs` this action supports. -To see real workflows making use of this action, see the [Pages starter-workflows][starter-workflows] that we publish. +For examples that make use of this action, check out our [starter-workflows][starter-workflows] in a variety of frameworks. This action expects an artifact to have been uploaded from the same workflow using [`actions/upload-pages-artifact`][upload-pages-artifact]. From 58b7d54130400307e516a832424ca88ed4e1a106 Mon Sep 17 00:00:00 2001 From: Yoann Chaudet Date: Tue, 26 Jul 2022 11:14:35 -0700 Subject: [PATCH 6/8] Update README.md Co-authored-by: Tommy Byrd --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index eba6df7..68825e5 100644 --- a/README.md +++ b/README.md @@ -52,7 +52,7 @@ There are a few important considerations to be aware of: 1. The artifact being deployed must have been uploaded in a previous step, either in the same job or a separate job that doesn't execute until the upload is complete. -2. The deployment step must at minimum have the following permissions: +2. The job that executes the deployment must at minimum have the following permissions: - `pages: write` - `id-token: write` From b4e423ab11ae3554a4463b8723258cb8befb7f5d Mon Sep 17 00:00:00 2001 From: Yoann Chaudet Date: Tue, 26 Jul 2022 11:14:52 -0700 Subject: [PATCH 7/8] Update README.md Co-authored-by: Tommy Byrd --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 68825e5..c5f272c 100644 --- a/README.md +++ b/README.md @@ -12,7 +12,7 @@ See [action.yml](action.yml) for the various `inputs` this action supports. For examples that make use of this action, check out our [starter-workflows][starter-workflows] in a variety of frameworks. -This action expects an artifact to have been uploaded from the same workflow using [`actions/upload-pages-artifact`][upload-pages-artifact]. +This action expects an artifact named `github-pages` to have been created prior to execution. This is done automatically using [`actions/upload-pages-artifact`][upload-pages-artifact]. We recommend this action to be used in a dedicated job: From 44ea2ec0c16bcb593fb0c1cc7d600423229a0780 Mon Sep 17 00:00:00 2001 From: Yoann Chaudet Date: Tue, 26 Jul 2022 11:16:01 -0700 Subject: [PATCH 8/8] Fix titles --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index c5f272c..35aad0f 100644 --- a/README.md +++ b/README.md @@ -46,7 +46,7 @@ jobs: uses: actions/deploy-pages@v1 ``` -# Security considerations +## Security considerations There are a few important considerations to be aware of: