GitHub Pages

Relevant source files

The following files were used as context for generating this wiki page:

• packages/github-pages/README.md
• packages/github-pages/project.json
• packages/github-pages/package.json
• packages/github-pages/CHANGELOG.md
• README.md

The @nx-extend/github-pages plugin enables the deployment of static applications to GitHub Pages directly from an Nx workspace. It automates the process of taking build artifacts from a local directory and pushing them to a specific branch in a GitHub repository.

Sources: packages/github-pages/README.md:1-12, README.md:46-48

Overview and Integration

This plugin operates as a library within the Nx ecosystem, providing executors to streamline CI/CD workflows. It specifically targets static site hosting and integrates with standard Nx build targets to identify deployment artifacts.

Key Capabilities

• Deploys static sites to a configurable GitHub branch.
• Automatically detects the outputPath from the project's build target.
• Integrates with GitHub Actions for automated deployment.
• Supports Nx version 22.0.0 and above.

Sources: packages/github-pages/README.md:5-12, packages/github-pages/package.json:5-7, packages/github-pages/CHANGELOG.md:11-19

Deployment Architecture

The deployment process relies on a specific executor that bridges the build output and the target GitHub repository.

Workflow Logic

The diagram shows the sequence from command execution to final deployment, highlighting the dependency on build outputs and authentication.

1. Build Execution: You must ensure the build target runs successfully before triggering the deployment.
2. Path Resolution: The executor reads the outputPath configuration from the project's build settings in project.json.
3. Authentication: The system uses the GH_PAGES_ACCESS_TOKEN environment variable to authenticate with GitHub.
4. Branch Update: Files from the output path are committed and pushed to the designated branch, which defaults to gh-pages.

Sources: packages/github-pages/README.md:27-48, packages/github-pages/README.md:65-68

Configuration

To use GitHub Pages, you define a deploy target within the project's project.json file.

Target Setup Example

{
  "targets": {
    "deploy": {
      "executor": "@nx-extend/github-pages:deploy",
      "options": {
        "branch": "gh-pages"
      }
    }
  }
}

Sources: packages/github-pages/README.md:37-43

Options and Environment Variables

The following table details the configurable options for the deployment executor:

Option	Type	Default	Description
branch	string	"gh-pages"	The target branch for hosting the site.

Sources: packages/github-pages/README.md:54-58

Required Environment Variables

Deployment requires the following environment variable to be set in your shell or CI environment:

Variable	Requirement	Description
GH_PAGES_ACCESS_TOKEN	Mandatory	A GitHub Personal Access Token with repository write permissions.

Sources: packages/github-pages/README.md:18-20, packages/github-pages/README.md:60-63

Technical Implementation Details

The plugin is structured as a standard Nx library with metadata defined in project.json.

The class diagram illustrates the relationship between the plugin definition, its internal targets, and the deployment executor.

Internal Project Structure

• Source Root: packages/github-pages/src
• Executor Entry: Defined in executors.json.
• Testing: Uses Jest with configuration in packages/github-pages/jest.config.ts.
• Dependencies: Depends on @nx/devkit for workspace interaction.

Sources: packages/github-pages/project.json:4-8, packages/github-pages/package.json:5-10, packages/github-pages/jest.config.ts:1-5

Usage Summary

To deploy a project named my-app, follow these steps:

1. Install the plugin using npm install -D @nx-extend/github-pages.
2. Set the GH_PAGES_ACCESS_TOKEN environment variable.
3. Configure the deploy target in project.json.
4. Run nx deploy my-app.

Sources: packages/github-pages/README.md:23-52