Switching GitHub Pages deployment from Classic to Actions-based deployment

GitHub has introduced another method to deploy your GitHub Pages website from the classic method to the modern deployment method from your GitHub Actions workflow. This avoids having to select a dedicated branch (usually called gh-pages) from your repository, which is separate from all your branches, including the main one.

This removes a huge overhead in having to maintain a separate branch dedicated for GitHub Pages files, which are static files that contain HTML, CSS, JS, and other website-related files. Instead, you can deploy your website straight from one branch and one workflow.

As part of our public apology for the API docs not being updated to take new design into account, we have first followed the steps that changed how the deployment works:

Go to a repository and navigate to Settings > Pages

In the Build and deployment section, click on the combo box

If it says Deploy from a branch, click on GitHub Actions

After that, we have edited the API documentation workflow so that it uses a more modern approach to deploying the docs site. The edits went like this for Textify (reference):

We have added read permission to the contents, and write permission to both the ID token and the GitHub Pages deployment.

permissions: contents: read pages: write id-token: write

We have added an environment, called github-pages, and set the deployment URL to the pages URL fetched from the deployment step.

environment: name: github-pages url: ${{ steps.deployment.outputs.page_url }}

We have replaced the peaceiris/actions-gh-pages@v3 action with the actions/upload-pages-artifact@v3 action.

We have specified the path to the output that DocFX generated in the build step.

- name: Saving changes to gh-pages uses: actions/upload-pages-artifact@v3 with: path: 'docs'

We have added a new step, whose ID is deployment, that uses actions/deploy-pages@v4.

- id: deployment uses: actions/deploy-pages@v4

After that, a commit that edited the workflow file was made, and the workflow has been run according to the rule that was set (to use the latest codebase found in the main branch):

on: push: branches: - main pull_request: branches: - main

As soon as this workflow ran, the Generate API Documentation workflow has run, and all steps went green! You can see the deployment logs below (after building the documentation):

Run actions/deploy-pages@v4 with: token: *** timeout: 600000 error_count: 10 reporting_interval: 5000 artifact_name: github-pages preview: false env: DOTNET_ROOT: /usr/share/dotnet Fetching artifact metadata for "github-pages" in this workflow run Found 1 artifact(s) Creating Pages deployment with payload: { "artifact_id": 5799820482, "pages_build_version": "b7cdd6b433d112ca575333cbfee3e92eb91ea304", "oidc_token": "***" } Created deployment for b7cdd6b433d112ca575333cbfee3e92eb91ea304, ID: b7cdd6b433d112ca575333cbfee3e92eb91ea304 Getting Pages deployment status... Reported success!

Finally, the API documentation has been generated and deployed to a github.io site for Textify, which you can find here. This has fixed issues related to outdated content appearing in the deployment, even though that deployment appeared to have been successful.

Our recommendation is that if you use the classic GitHub Pages deployment method, you should consider migrating to the modern method, after studying implications and migration costs, depending on how the deployment is made.

#github #GitHubPages #news #Tech #Technology #update