GitHub Actions is GitHub’s continuous integration service, launched in October 2018. I’ve been experimenting with it these days and find it very powerful, creative, and more than Travis CI gameplay.

This is a simple tutorial that demonstrates how to use GitHub Actions to automatically publish a VuePress application to GitHub Pages.

VuePress document

Official documentation: Links

  1. Create and enter a new directory
mkdir vuepress-starter && cd vuepress-starter
Copy the code
  1. Initialize using your favorite package manager
yarn init # npm init
Copy the code
  1. Install VuePress as a local dependency
yarn add -D vuepress # npm install -D vuepress
Copy the code
  1. Create your first document
mkdir docs && echo '# Hello VuePress' > docs/README.md
Copy the code
  1. Add some scripts to package.json (Open New Window)
{
  "scripts": {
    "docs:dev": "vuepress dev docs",
    "docs:build": "vuepress build docs"
  }
}
Copy the code
  1. Start the server locally
yarn docs:dev # npm run docs:dev
Copy the code

VuePress launches a hot-loaded development server at http://localhost:8080 (opens New Window).

  1. Set the correct base in docs/.vuepress/config.js.

If you want to post to https://

.github. IO /, you can skip this step, because base is “/” by default.

If you want to post to https://

.github. IO /

/ (that is, your repository is at https://github.com/

/

), Then set base to “/

/”.




Create a dead simple Actions

As you know, continuous integration consists of many operations, such as grabbing code, running tests, logging into remote servers, publishing to third-party services, and so on. GitHub calls these actions actions.

Select Actions from the warehouse menu bar to go to the Create page.

Simply modify the command you need to execute:

# This is a basic workflow to help you get started with Actions

name: CI

# Controls when the action will run. 
on:
  # Triggers the workflow on push or pull request events but only for the master branch
  push:
    branches: [ master ]
  pull_request:
    branches: [ master ]

  # Allows you to run this workflow manually from the Actions tab
  workflow_dispatch:

# A workflow run is made up of one or more jobs that can run sequentially or in parallel
jobs:
  # This workflow contains a single job called "build"
  build:
    # The type of runner that the job will run on
    runs-on: ubuntu-latest

    # Steps represent a sequence of tasks that will be executed as part of the job
    steps:
      # Checks-out your repository under $GITHUB_WORKSPACE, so your job can access it
      - uses: actions/checkout@v2

      # Runs a single command using the runners shell
      - name: Run a ci script
        run: npm ci
      - name: Run a docs script
        env:
          TOKEN: ${{secrets.HEXO_DEPLOY_PRIVATE_KEY}}
        run: npm run docs
      # Runs a set of commands using the runners shell
      - name: Run a multi-line script
        run: |
          echo Add other actions to build,
          echo test, and deploy your project.
Copy the code

The GitHub Actions configuration file is called the Workflow file and is stored in the. GitHub /workflows directory of the repository.

Workflow files are in YAML format. The file name can be arbitrary, but the file name extension is.yml, for example, foo.yml. A library can have multiple Workflow files. GitHub automatically runs a. Yml file when it is found in the. GitHub /workflows directory.

For a detailed description of fields, see this article: Links.

Because there is an environment variable TOKEN defined in the code: ${{secrets.hexo_deploy_private_key}} for git SSH secret free logins, you cannot git push these operations without configuring it.

This example needs to send the build to the GitHub repository, so the GitHub key is required. Follow the official documentation: link to generate a key.

Then, store this key in Settings/Secrets of the current repository.

Finally, create the file build/update-docs.sh to execute the bash script.

# Prepare
cd docs
rm -rf .vuepress/dist

# Build
vuepress build

# Publish to GitHub Pages
cd .vuepress/dist
git init
git config user.name "wuxianqiang"
git config user.email "[email protected]"
git add -A
git commit -m "[vuepress] update docs"
git push --force "https://${TOKEN}@github.com/wuxianqiang/vuepress-starter.git" "master:gh-pages"

# Cleanup
cd ../..
rm -rf .vuepress/dist
Copy the code

Add a line of scripts to package.json.

{
  "scripts": {
    "docs:dev": "vuepress dev docs",
    "docs:build": "vuepress build docs",
    "docs": "bash ./build/update-docs.sh"
  }
}
Copy the code

Finally, the code is submitted and Actions is automatically executed to deploy the VuePress document to GitHub Pages. We can access the page, and every subsequent submission will be automatically executed to update the content of the document, which really makes it a lot easier.

Project demo address: link