{"meta":{"title":"Using custom workflows with GitHub Pages","intro":"You can take advantage of using GitHub Actions and GitHub Pages by creating a workflow file or choosing from the predefined workflows.","product":"GitHub Pages","breadcrumbs":[{"href":"/en/pages","title":"GitHub Pages"},{"href":"/en/pages/getting-started-with-github-pages","title":"Get started"},{"href":"/en/pages/getting-started-with-github-pages/using-custom-workflows-with-github-pages","title":"Use custom workflows"}],"documentType":"article"},"body":"# Using custom workflows with GitHub Pages\n\nYou can take advantage of using GitHub Actions and GitHub Pages by creating a workflow file or choosing from the predefined workflows.\n\n## About custom workflows\n\nCustom workflows allow GitHub Pages sites to be built via the use of GitHub Actions. You can still select the branch you would like to use via the workflow file, but you are able to do much more with the use of custom workflows. To start using custom workflows you must first enable them for your current repository. For more information, see [Configuring a publishing source for your GitHub Pages site](/en/pages/getting-started-with-github-pages/configuring-a-publishing-source-for-your-github-pages-site#publishing-with-a-custom-github-actions-workflow).\n\n## Configuring the `configure-pages` action\n\nGitHub Actions enables the use of GitHub Pages through the `configure-pages` action, which also lets you gather different metadata about a website. For more information, see the [`configure-pages`](https://github.com/marketplace/actions/configure-github-pages) action.\n\nTo use the action place this snippet under your `jobs` in the desired workflow.\n\n```yaml\n- name: Configure GitHub Pages\n  uses: actions/configure-pages@v5\n```\n\nThis action helps support deployment from any static site generator to GitHub Pages. To make this process less repetitive you can use workflow templates for some of the most widely used static site generators. For more information, see [Using workflow templates](/en/actions/how-tos/write-workflows/use-workflow-templates).\n\n## Configuring the `upload-pages-artifact` action\n\nThe `upload-pages-artifact` actions enables you to package and upload artifacts. The GitHub Pages artifact should be a compressed `gzip` archive containing a single `tar` file. The `tar` file must be under 10GB in size and should not contain any symbolic or hard links. For more information, see the [`upload-pages-artifact`](https://github.com/marketplace/actions/upload-github-pages-artifact) action.\n\nTo use the action in your current workflow place this snippet under `jobs`.\n\n```yaml\n- name: Upload GitHub Pages artifact\n  uses: actions/upload-pages-artifact@v4\n```\n\n## Deploying GitHub Pages artifacts\n\nThe `deploy-pages` action handles the necessary setup for deploying artifacts. To ensure proper functionality, the following requirements should be met:\n\n* The job must have a minimum of `pages: write` and `id-token: write` permissions.\n* The `needs` parameter must be set to the `id` of the build step. Not setting this parameter may result in an independent deployment that continuously searches for an artifact that hasn't been created.\n* An `environment` must be established to enforce branch/deployment protection rules. The default environment is `github-pages`.\n* To specify the URL of the page as an output, utilize the `url:` field.\n\nFor more information, see the [`deploy-pages`](https://github.com/marketplace/actions/deploy-github-pages-site) action.\n\n```yaml\n# ...\n\njobs:\n  deploy:\n    permissions:\n      contents: read\n      pages: write\n      id-token: write\n    runs-on: ubuntu-latest\n    needs: jekyll-build\n    environment:\n      name: github-pages\n      url: ${{steps.deployment.outputs.page_url}}\n    steps:\n      - name: Deploy artifact\n        id: deployment\n        uses: actions/deploy-pages@v4\n# ...\n```\n\n## Linking separate build and deploy jobs\n\nYou can link your `build` and `deploy` jobs in a single workflow file, eliminating the need to create two separate files to get the same result. To get started on your workflow file, under `jobs` you can define a `build` and `deploy` job to execute your jobs.\n\n```yaml\n# ...\n\njobs:\n  # Build job\n  build:\n    runs-on: ubuntu-latest\n    steps:\n      - name: Checkout\n        uses: actions/checkout@v6\n      - name: Setup Pages\n        id: pages\n        uses: actions/configure-pages@v5\n      - name: Build with Jekyll\n        uses: actions/jekyll-build-pages@v1\n        with:\n          source: ./\n          destination: ./_site\n      - name: Upload artifact\n        uses: actions/upload-pages-artifact@v4\n\n  # Deployment job\n  deploy:\n    environment:\n      name: github-pages\n      url: ${{steps.deployment.outputs.page_url}}\n    runs-on: ubuntu-latest\n    needs: build\n    steps:\n      - name: Deploy to GitHub Pages\n        id: deployment\n        uses: actions/deploy-pages@v4\n# ...\n```\n\nIn certain cases, you might choose to combine everything into a single job, especially if there is no need for a build process. Consequently, you would solely focus on the deployment step.\n\n```yaml\n# ...\n\njobs:\n  # Single deploy job no building\n  deploy:\n    environment:\n      name: github-pages\n      url: ${{steps.deployment.outputs.page_url}}\n    runs-on: ubuntu-latest\n    steps:\n      - name: Checkout\n        uses: actions/checkout@v6\n      - name: Setup Pages\n        uses: actions/configure-pages@v5\n      - name: Upload Artifact\n        uses: actions/upload-pages-artifact@v4\n        with:\n          # upload entire directory\n          path: '.'\n      - name: Deploy to GitHub Pages\n        id: deployment\n        uses: actions/deploy-pages@v4\n\n# ...\n```\n\nYou can define your jobs to be run on different runners, sequentially, or in parallel. For more information, see [Choosing what your workflow does](/en/actions/how-tos/write-workflows/choose-what-workflows-do)."}