How to Deploy GitHub Pages Using GitHub Actions?

jobs:
  build:
  deploy:
    needs: build
    permissions:
      pages: write      # to deploy to Pages
      id-token: write   # to verify the deployment originates from an appropriate source
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    runs-on: ubuntu-latest
    steps:
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v4 # or specific "vX.X.X" version tag for this action

deploy-pages

GitHub Action to publish artifacts to GitHub Pages for deployments

deploy-pages GitHub Action automates the deployment process, ensuring that our site is always up-to-date with the latest changes. This setup also incorporates security best practices to protect our deployment process.

By automating the deployment of GitHub Pages, we ensure a seamless and efficient process that reduces manual intervention and potential errors. This approach also enhances security by adhering to GitHub's permissions and token requirements.

How to configure the inputs for the deploy action?​

• Inputs for deploy-pages Action:
  • token: The GitHub token used to create an authenticated client.
    • Example: ${{ github.token }}
  • timeout: Time in milliseconds after which to timeout and cancel the deployment.
    • Default: "600000" (10 minutes)
  • error_count: Maximum number of status report errors before cancelling a deployment.
    • Default: "10"
  • reporting_interval: Time in milliseconds between two deployment status reports.
    • Default: "5000" (5 seconds)
  • artifact_name: The name of the artifact to deploy.
    • Default: "github-pages"
  • preview: Indicates if the deployment is a preview for a pull request.
    • Default: "false"

Configuring these inputs allows for customized deployment behavior, ensuring it fits the project's specific needs. Adjusting the timeout and error count can help manage deployment stability.

How to handle security considerations?​

• Permissions Required:
  • pages: write: Grants permission to deploy to Pages.
  • id-token: write: Verifies the deployment originates from an appropriate source.

Ensuring the correct permissions are set is crucial for a secure deployment. The id-token permission is necessary for requesting the OIDC JWT token, which is used to validate the workflow's branch protection settings.

• Artifact Requirements:
  • The artifact must be uploaded in a previous step.
  • Ensure the deployment job has the necessary permissions.

Uploading the artifact in a previous step ensures that the deployment job has access to the required files. This practice also separates concerns, making the workflow more modular and easier to maintain.

How to use OIDC tokens?​

• OIDC Tokens in Deployments:
  • OIDC tokens are used to form a trust relationship that validates workflow properties against third-party services (e.g., AWS, Azure).
  • The token includes claims about the branch/ref executing the workflow, ensuring compliance with branch protection settings.

Understanding and correctly using OIDC tokens enhances security by ensuring that only authorized workflows can deploy to GitHub Pages. This approach also aligns with best practices for secure CI/CD pipelines.