From c1761a47d82da070b1d3bd702c9a5da853c1562a Mon Sep 17 00:00:00 2001 From: Jan Suchotzki Date: Wed, 22 May 2024 16:01:45 +0200 Subject: [PATCH 1/3] Adds required permission for GitHub deployment Based on the discussions in https://github.com/orgs/statiqdev/discussions/221 as well as in https://github.com/statiqdev/Statiq.Web/issues/1021 the documentation is updated. --- input/guide/deployment/github-pages.md | 12 +++++++++--- 1 file changed, 9 insertions(+), 3 deletions(-) diff --git a/input/guide/deployment/github-pages.md b/input/guide/deployment/github-pages.md index bc84182..d88e2ae 100644 --- a/input/guide/deployment/github-pages.md +++ b/input/guide/deployment/github-pages.md @@ -2,7 +2,7 @@ Badge: Web --- Statiq can be configured to deploy to [GitHub Pages](https://pages.github.com). -Note that GitHub Pages must be activated for the target repository [according to the instructions](https://docs.github.com/en/pages/getting-started-with-github-pages/creating-a-github-pages-site) before deploying to it. +Note that GitHub Pages must be activated for the target repository [according to the instructions](https://docs.github.com/en/pages/getting-started-with-github-pages/creating-a-github-pages-site) before deploying to it. Using the deployment pipeline described here requires that GitHub Pages are configured to be published from a branch [like described here](https://docs.github.com/en/pages/getting-started-with-github-pages/configuring-a-publishing-source-for-your-github-pages-site#publishing-from-a-branch). The following [settings](xref:web-settings) are used to configure deployment to GitHub Pages: @@ -11,7 +11,7 @@ The following [settings](xref:web-settings) are used to configure deployment to - `GitHubUsername`: The username to use for deployment. - `GitHubPassword`: The password to use for deployment. - `GitHubToken`: The token to use for deployment (configure either this _or_ username and password). If deploying from a GitHub Action (see below), you should use a [computed value](xref:metadata-values#computed-values) to get the value of "GITHUB_TOKEN" for this value: `=> Config.FromSetting("GITHUB_TOKEN")`. -- `GitHubBranch`: The branch to deploy to (defaults to `gh-pages` but you should change this to the configured GitHub Pages branch such as `main` or `master` for organization sites). +- `GitHubBranch`: The branch to deploy to (defaults to `gh-pages` but you should change this to the configured GitHub Pages branch such as `main` or `master` for organization sites). Be aware that the generated site will be pushed into this branch! It's customary to set one or more of these settings as an environment variable in continuous integration environments (particularly secrets like the password). In these scenarios you can either @@ -70,6 +70,10 @@ to deploy a Statiq site: name: Deploy Site on: [push] +# Sets permissions of the GITHUB_TOKEN to allow writing the content to the branch! +permissions: + contents: write + jobs: build: runs-on: windows-latest @@ -89,4 +93,6 @@ jobs: Note that you don't need to call `DeployToGitHubPages` or `DeployToGitHubPagesBranch` if you're specifying the `GitHubOwner`, `GitHubName`, `GitHubToken`, (and optionally `GitHubBranch`) settings elsewhere (like an `appsettings.json` file). These methods are just a convenience for setting those values. The -GitHub deployment will automatically take place if those settings are defined, regardless of how or where they were set. \ No newline at end of file +GitHub deployment will automatically take place if those settings are defined, regardless of how or where they were set. + +Keep in mind that although this approach can use a GitHub Action (as shown above), there is an alternative way of using GitHub Actions for deployment to GitHub pages. From d8645d965c6daa5326d536714c135e698dca4574 Mon Sep 17 00:00:00 2001 From: Jan Suchotzki Date: Wed, 22 May 2024 16:07:20 +0200 Subject: [PATCH 2/3] Describes performance differences in github-pages.md While debugging for https://github.com/statiqdev/Statiq.Web/issues/1021 I realized that the GitHub Action is much faster on ubuntu compared to windows. --- input/guide/deployment/github-pages.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/input/guide/deployment/github-pages.md b/input/guide/deployment/github-pages.md index d88e2ae..ae1b3df 100644 --- a/input/guide/deployment/github-pages.md +++ b/input/guide/deployment/github-pages.md @@ -95,4 +95,6 @@ Note that you don't need to call `DeployToGitHubPages` or `DeployToGitHubPagesBr settings elsewhere (like an `appsettings.json` file). These methods are just a convenience for setting those values. The GitHub deployment will automatically take place if those settings are defined, regardless of how or where they were set. +When using GitHub Actions (as shown above) there is a huge performance difference between running the deployment on `windows-latest` compared to `ubuntu-latest`. Using `ubuntu-latest` is around 3 times faster. + Keep in mind that although this approach can use a GitHub Action (as shown above), there is an alternative way of using GitHub Actions for deployment to GitHub pages. From f5f3feefa679d9ef55b483c4263b94536719ca41 Mon Sep 17 00:00:00 2001 From: Jan Suchotzki Date: Wed, 22 May 2024 16:09:10 +0200 Subject: [PATCH 3/3] Updates actions on github-pages.md Using the latest actions/setup-dotnet is faster and properly supports the actual dotnet version. --- input/guide/deployment/github-pages.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/input/guide/deployment/github-pages.md b/input/guide/deployment/github-pages.md index ae1b3df..77fd52f 100644 --- a/input/guide/deployment/github-pages.md +++ b/input/guide/deployment/github-pages.md @@ -81,9 +81,9 @@ jobs: - uses: actions/checkout@master with: submodules: recursive - - uses: actions/setup-dotnet@v1 + - uses: actions/setup-dotnet@v4 with: - dotnet-version: '3.1.100' # SDK Version to use. + dotnet-version: '8.x' # SDK Version to use. - run: dotnet run -- deploy env: GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}