Skip to content

VuePress GitHub Actions Deployment

VuePress GitHub Actions Deployment is an automated workflow configuration that enables the continuous deployment of a VuePress project to a GitHub repository (such as a GitHub Pages site) whenever code is pushed to the main branch.^[600-developer__blog__vuepress-blog__vuepress-init.md]

Workflow Configuration

The deployment process is defined in a YAML file, typically located at .github/workflows/ci.yml.^[600-developer__blog__vuepress-blog__vuepress-init.md] The configuration generally consists of three main stages: source acquisition, environment setup, and deployment.^[600-developer__blog__vuepress-blog__vuepress-init.md]

Triggers

The workflow is designed to run automatically under specific conditions.^[600-developer__blog__vuepress-blog__vuepress-init.md]

  • Push events: The deployment triggers whenever code is pushed to the main branch.^[600-developer__blog__vuepress-blog__vuepress-init.md]
  • Manual dispatch: The workflow can also be triggered manually via the GitHub interface.^[600-developer__blog__vuepress-blog__vuepress-init.md]

Execution Steps

The job typically runs on an ubuntu-latest environment and involves the following steps:^[600-developer__blog__vuepress-blog__vuepress-init.md]

  1. Checkout: This step uses actions/checkout@v3 to clone the repository.^[600-developer__blog__vuepress-blog__vuepress-init.md] It is configured with fetch-depth: 0 to ensure that the full git history is retrieved, which is necessary for displaying accurate "Last Updated" timestamps.^[600-developer__blog__vuepress-blog__vuepress-init.md]
  2. Node Setup: The environment is prepared using actions/setup-node@v3 to install a specific version of Node.js (e.g., 16.3.0).^[600-developer__blog__vuepress-blog__vuepress-init.md]
  3. Clean and Install: The workflow cleans the build directory (usually ./public) and runs npm install -D to install project dependencies.^[600-developer__blog__vuepress-blog__vuepress-init.md]
  4. Deploy: Finally, an action such as jenkey2011/vuepress-deploy@master is used to execute the build script and push the output to the target repository.^[600-developer__blog__vuepress-blog__vuepress-init.md]

Environment Variables

The deployment step requires specific environment variables to authenticate and identify the target location.^[600-developer__blog__vuepress-blog__vuepress-init.md]

  • ACCESS_TOKEN: A Personal Access Token stored in the repository's secrets, allowing the workflow to write to the target repository.^[600-developer__blog__vuepress-blog__vuepress-init.md]
  • TARGET_REPO: The GitHub repository where the static files will be deployed (e.g., username/repo.github.io).^[600-developer__blog__vuepress-blog__vuepress-init.md]
  • TARGET_BRANCH: The branch in the target repository that will be updated (e.g., master).^[600-developer__blog__vuepress-blog__vuepress-init.md]
  • BUILD_SCRIPT: The command to build the VuePress site (typically npm run build).^[600-developer__blog__vuepress-blog__vuepress-init.md]
  • BUILD_DIR: The directory where the build output is generated, which matches the dest configuration in config.js (usually public).^[600-developer__blog__vuepress-blog__vuepress-init.md]

Configuration Requirements

To ensure the deployment functions correctly with VuePress and the source repository, specific configurations are necessary:

  • Build Directory: The config.js must define a dest field (e.g., 'public') specifying the output folder.^[600-developer__blog__vuepress-blog__vuepress-init.md]
  • Path Constraints: File paths in the project should not contain Chinese characters to prevent build errors.^[600-developer__blog__vuepress-blog__vuepress-init.md]
  • Relative Links: Image links should use relative paths.^[600-developer__blog__vuepress-blog__vuepress-init.md]

Sources

^[600-developer__blog__vuepress-blog__vuepress-init.md]