Skip to main content
← Back to workflows

How to Deploy GitHub Pages Using GitHub Actions?

actions/deploy-pages -
GitHub Action
v4.0.5
641
Contributors
Contributor - JamesMGreeneContributor - YiMysty
Categories
CICUBE ANALYTICS INSIGHTS
Engineering Velocity: 25% Team Time Lost to CI Issues
View Platform →
3.5h
Time Saved/Dev/Week
40%
Faster Releases
Click for next insight
Usage
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 logo

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.