🔙 Go back home

GitHub Actions Workflow: Prepare and Deploy Artifact

This document explains the structure and functionality of a GitHub Actions workflow designed to prepare and deploy artifacts for a GitHub Pages site. The workflow is manually triggered (workflow_dispatch) and includes two main jobs: prepare_deploy_artifact and deploy.

Workflow Triggers

The workflow is triggered manually via the Run workflow button in the GitHub UI. It requires the following inputs:

1. PageName:
   • Description: Name of the artifact generated during the page generation process.
   • Required: Yes
   • Default: latest
2. PagePipelineID:
   • Description: Pipeline ID of the workflow run that generated the page artifact.
   • Required: Yes
   • Default: latest
3. PackageName:
   • Description: Name of the artifact generated during the package build process.
   • Required: Yes
   • Default: latest
4. PackagePipelineID:
   • Description: Pipeline ID of the workflow run that generated the package artifact.
   • Required: Yes
   • Default: latest

Jobs in the Workflow

1. Prepare and Deploy Artifact Job (prepare_deploy_artifact)

Environment:

• Runs on: ubuntu-latest.

Steps:

1. Download Pages Artifact:
   • Downloads the artifact generated during the page generation process into the pages directory.
   • Uses the actions/download-artifact@v4 action with the provided PageName and PagePipelineID.
2. Download Packages Artifact:
   • Downloads the artifact generated during the package build process into the pages directory.
   • Uses the actions/download-artifact@v4 action with the provided PackageName and PackagePipelineID.
3. List Files:
   • Lists the contents of the pages directory to verify that the artifacts were downloaded successfully.
4. Upload Combined Artifact:
   • Uploads the combined contents of the pages directory as a new artifact named deploy_artifact using actions/upload-pages-artifact@v3.

2. Deploy Job (deploy)

Conditions:

• Runs only if the trigger is from the main branch (github.ref == 'refs/heads/main').
• Depends on the successful completion of the prepare_deploy_artifact job.

Permissions:

• Grants the necessary permissions for deploying to GitHub Pages:
  • contents: read
  • pages: write
  • id-token: write

Environment:

• Specifies the github-pages environment.
• Sets the URL of the deployed site to $.

Steps:

1. Deploy to GitHub Pages:
   • Deploys the previously uploaded artifact (deploy_artifact) to GitHub Pages using actions/deploy-pages@v4.

Key Features

1. Manual Triggering:
   • The workflow is designed to be manually triggered, allowing flexibility in specifying the artifacts and pipeline IDs.
2. Artifact Management:
   • Combines artifacts from two separate workflows (page generation and package build) into a single directory (pages) for deployment.
3. Environment Configuration:
   • Configures the github-pages environment with appropriate permissions and outputs the deployed site’s URL.
4. Verification:
   • Includes a step to list the contents of the pages directory, ensuring that the artifacts are correctly downloaded before proceeding.

Example Use Case

This workflow is ideal for automating the deployment of a GitHub Pages site that relies on artifacts generated by multiple upstream workflows. For example:

• The PageGeneration workflow generates static HTML files for documentation.
• The build_packages workflow generates downloadable assets (e.g., ISOs or binaries).

By combining these artifacts into a single directory and deploying them to GitHub Pages, you can create a unified site that hosts both documentation and downloadable assets.