diff --git a/Dockerfile b/Dockerfile deleted file mode 100644 index 65261f7..0000000 --- a/Dockerfile +++ /dev/null @@ -1,18 +0,0 @@ -FROM node:10 - -# Set default locale for the environment -ENV LC_ALL C.UTF-8 -ENV LANG en_US.UTF-8 -ENV LANGUAGE en_US.UTF-8 - -LABEL "com.github.actions.name"="Build & Deploy to GitHub Pages" -LABEL "com.github.actions.description"="Builds & deploys Jekyll to gh-pages branch of the same repository. " -LABEL "com.github.actions.icon"="globe" -LABEL "com.github.actions.color"="green" - -LABEL "repository"="https://github.com/le0tan/markbind-deploy-gh-pages" - -ADD entrypoint.sh /entrypoint.sh -RUN chmod +x entrypoint.sh - -ENTRYPOINT ["/entrypoint.sh"] \ No newline at end of file diff --git a/README.md b/README.md index 350d0d2..82d6ec6 100644 --- a/README.md +++ b/README.md @@ -1,34 +1,281 @@ # markbind-action - A GitHub Action that builds and deploys your MarkBind site. -## How to use this action? +## Option Summary + +Option | Required | Default | Remarks +:-----------------------|:--------:|---------------:|----------------------------------------------------------------- +[token](#token) | yes | | The token to be used for the service +[service](#service) | no | `'gh-pages'` | The publishing service to deploy the site +[purpose](#purpose) | no | `'deployment'` | The deployment purpose +[domain](#domain) | no | `''` | The domain that the site is available at +[version](#version) | no | `'latest'` | The MarkBind version to use to build the site +[keepFiles](#keepFiles) | no | `false` | Whether to keep the files in the published branch before pushing +[rootDirectory](#rootdirectory-markbind-cli-arguments) | no | `'.'` | The directory to read source files from +[baseUrl](#baseurl-markbind-cli-arguments) | no | Value specified in site.json | The base URL relative to your domain +[siteConfig](#siteconfig-markbind-cli-arguments) | no | `'site.json'` | The site config file to use + +## Option Details + +### token +Currently two types of tokens are supported (correspond to the two supported publishing services): +- Token for GitHub Pages + - Simply use `${{ secrets.GITHUB_TOKEN }}` + - Note that you need to ensure that you have selected the branch that you want to deploy to in your [GitHub repo's Pages settings](https://docs.github.com/en/pages/getting-started-with-github-pages/configuring-a-publishing-source-for-your-github-pages-site#choosing-a-publishing-source) + - Deployment to GitHub Pages might take 5-10 minutes before the site is available/refreshed +- Token for Surge.sh + - `${{ secrets.SURGE_TOKEN }}` + - `SURGE_TOKEN` is the environment secret name + - Require registration with an email address + - After retrieving the token, put the token as a repository secret in your repository + - See [here](https://markbind.org/userGuide/deployingTheSite.html#previewing-prs-using-surge) for a detailed guide on how to retrieve the token + +### service +Currently two types of publishing services are supported: +- GitHub Pages + - `'gh-pages'` + - See [here](https://markbind.org/userGuide/deployingTheSite.html#publishing-to-github-pages) for more details +- Surge.sh + - `'surge'` + - See [here](https://surge.sh/) for more details + +### purpose +The purpose of the deployment. This can either be standard deployment or for PR preview. +- Standard deployment + - `'deployment'` + - This is the default value +- PR preview + - `'pr-preview'` + - This is used if you want to build and preview the updated site whenever there is a PR made to the repository + - The `service` must be `'surge'` and the `domain` must be specified + - Note that this does not work for PR from a fork (due to security reasons) + - This action will not automatically cleanup merged PR deployments. Follow this [instruction](https://surge.sh/help/tearing-down-a-project) to manually tear down the deployed site if required + +### domain +The domain that the site is available at. Required if `service` chosen is Surge. +- A surge.sh subdomain + - `'.surge.sh'` + - Surge allows you to specify a subdomain for free as long as it has not been taken up by others. You have to ensure that the `` is unique. + - A possible subdomain to use is your repository name: e.g. `mb-test.surge.sh` +- A custom domain that you have configured with Surge + - Read the [Surge documentation](https://surge.sh/help/adding-a-custom-domain) to understand how to set it up +- Additional notes + - for PR preview purposes, the domain you specify will automatically be prefixed with 'pr-x-', where 'x' is the GitHub event number + - E.g. `'pr-x-'` (and hence `'pr-1-mb-test.surge.sh'`) + - Custom domain does not work with PR preview + - This action will not automatically cleanup merged PR deployments. Follow this [instruction](https://surge.sh/help/tearing-down-a-project) to manually tear down the deployed site if required + +### version +The MarkBind version to use to build the site. +- Latest + - `'latest'` + - This is the latest published version of MarkBind +- Development + - `'development'` + - This is the latest, possibly unpublished version of MarkBind in development +- Any valid version + - `'X.Y.Z'` + - This is the version of MarkBind with the specified version number + - E.g. `'3.1.1'` +- Any valid version range + - Internally the action calls [`npm install`](https://docs.npmjs.com/cli/v6/commands/npm-install) to install the specified version of MarkBind + - Hence, a version range such as `'>=3.0.0'` (or semantic versioning like `'^3.1.1'`) is also valid + +### keepFiles +Whether to keep the files in the published branch before pushing. This is a boolean parameter. +- Keep + - `false` + - This is the default value +- Don't keep + - `true` + - This will preserve any existing files in the published branch before an update is made. + +### rootDirectory (MarkBind CLI arguments) +The directory to read source files from. +- Root + - `'.'` + - This is the default value + - This is for the case that your source files of the MarkBind site are in the root directory of the repository +- Any subdirectory + - `'./path/to/directory'` + - This is for the case that your source files of the MarkBind site are in a subdirectory of the repository + - E.g. `'./docs'` + +### baseUrl (MarkBind CLI arguments) +The base URL relative to your domain. +- Default + - The value of `baseUrl` in the site config file (typically `site.json`) +- Any valid base URL + - For GitHub Pages, you will need to specify this here or in the site config file, in order to configure the relative URL correctly. + - e.g. `'/reponame'` + - For Surge, you will need to ensure that it's specfied as `''` here or in the site config file. + +### siteConfig (MarkBind CLI arguments) +The site config file to use. +- Default site config file + - `'site.json'` + - This is the default value +- Name of your site config file + - If your site config file is not named `site.json`, specify the name here + - E.g. `'ug-site.json'` + +# Usage +In essence, there are two parts to a GitHub Action workflow: +- The trigger event +- The jobs/steps to be run after the trigger event occurs + +For our context, there are two typical trigger events. This is written at the start of a workflow file: +(Assuming 'master' is the target branch) +1. Trigger the action whenever there is a push to the repository +```yaml +on: + push: + branches: + - master +``` + +2. Trigger the action whenever there is a pull request to the repository +```yaml +on: + pull_request: + branches: + - master +``` + +Then, specify a step to use this action: -Make sure that your MarkBind project is on the master branch. +E.g. +```yaml +name: MarkBind Action + +on: + push: + branches: + - master + +jobs: + build_and_deploy: + runs-on: ubuntu-latest + steps: + - name: Build & Deploy MarkBind site + uses: MarkBind/markbind-action@v2 + with: + token: ${{ secrets.GITHUB_TOKEN }} + baseUrl: '/mb-test' + version: '3.1.1' +``` +The above script builds the site from the repository's root directory, with `baseUrl` of '/mb-test' ('mb-test' is the repository name), with MarkBind version 3.1.1. -1. On the top of your repo, click **Actions** -2. Click **New workflow** -3. Click **Set up workflow yourself** on the top right corner -4. Configure your `main.yml` as follows (note that you need to specify the **BASE_URL** of your GitHub pages) +Then, it will deploy the site to GitHub Pages. It runs everytime there is a push to the repository's master branch. +# Recipes +## Deploy to Github Pages on push to main ```yaml -name: MarkBind Deploy +name: MarkBind Action -on: [push] +on: + push: + branches: + - main jobs: build_and_deploy: runs-on: ubuntu-latest steps: - - uses: actions/checkout@v1 - - name: Build & Deploy to GitHub Pages - env: - GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} - GITHUB_REPOSITORY: ${{ secrets.GITHUB_REPOSITORY }} - GITHUB_ACTOR: ${{ secrets.GITHUB_ACTOR }} - BASE_URL: # base URL to your gh-page - uses: MarkBind/markbind-action@1.0.0 + - name: Build & Deploy MarkBind site + uses: MarkBind/markbind-action@v2 + with: + token: ${{ secrets.GITHUB_TOKEN }} + version: '3.1.1' +``` + +## Deploy to Surge.sh +```yaml +name: MarkBind Action + +on: + push: + branches: + - main +jobs: + build_and_deploy: + runs-on: ubuntu-latest + steps: + - name: Build & Deploy MarkBind site + uses: MarkBind/markbind-action@v2 + with: + token: ${{ secrets.SURGE_TOKEN }} + service: 'surge' + domain: 'mb-test.surge.sh' +``` + +## Build with the latest developmental version of MarkBind +```yaml +name: MarkBind Action + +on: + push: + branches: + - main + +jobs: + build_and_deploy: + runs-on: ubuntu-latest + steps: + - name: Build & Deploy MarkBind site + uses: MarkBind/markbind-action@v2 + with: + token: ${{ secrets.GITHUB_TOKEN }} + version: 'development' +``` + +## Build with files that is not at the root level of the repository +```yaml +name: MarkBind Action + +on: + push: + branches: + - main + +jobs: + build_and_deploy: + runs-on: ubuntu-latest + steps: + - name: Build & Deploy MarkBind site + uses: MarkBind/markbind-action@v2 + with: + token: ${{ secrets.GITHUB_TOKEN }} + rootDirectory: './docs' +``` + +## PR preview for PRs made within the same repository +```yaml +name: MarkBind Action + +on: + pull_request: + branches: + - main + +jobs: + build_and_deploy: + runs-on: ubuntu-latest + steps: + - name: Build & Deploy MarkBind site + uses: MarkBind/markbind-action@v2 + with: + token: ${{ secrets.SURGE_TOKEN }} + service: 'surge' + purpose: 'pr-preview' + domain: 'mb-test.surge.sh' ``` -This action will be triggered on push, and built files will be in `gh-pages` branch of the same repo. +## Behind the Scenes +Besides processing a few bash scripts, this action utilises the following actions: +- [actions/checkout](https://github.com/actions/checkout) +- [actions/setup-node](https://github.com/actions/setup-node) +- [peter-evans/find-comment](https://github.com/peter-evans/find-comment) +- [peter-evans/create-or-update-comment](https://github.com/peter-evans/create-or-update-comment) +- [peaceiris/actions-gh-pages](https://github.com/peaceiris/actions-gh-pages) \ No newline at end of file diff --git a/action.yml b/action.yml index 9e168dd..d3ce5ca 100644 --- a/action.yml +++ b/action.yml @@ -1,8 +1,131 @@ name: markbind-action -description: 'A GitHub Action that builds and deploys your MarkBind site.' +description: 'Deploy your MarkBind site' branding: icon: 'upload-cloud' color: 'blue' + +inputs: + token: + description: the required token + required: true + service: + description: the publishing service + default: 'gh-pages' + type: string + purpose: + description: the deployment purpose, could be standard deployment or for PR preview + default: 'deployment' + type: string + domain: + description: the domain to use + type: string + version: + description: the MarkBind version to use. e.g. 3.1.1 + default: 'latest' + type: string + rootDirectory: + description: the directory to read source files from + default: '.' + type: string + baseUrl: + description: the base URL relative to your domain + default: 'unsetFlag' # a flag indicating that baseUrl defaults to the one specified in site.json config file + type: string + siteConfig: + description: the site config file to use + default: 'site.json' + type: string + keepFiles: + description: whether the existing files will be removed in the published branch, before pushing. + default: false + type: boolean + runs: - using: 'docker' - image: 'Dockerfile' \ No newline at end of file + using: "composite" + steps: + - name: Checkout source repo + uses: actions/checkout@v3 + with: + path: curr-repo + - name: Install Node + uses: actions/setup-node@v2 + with: + node-version: 12 + - name: Checkout markbind-cli@master + if: inputs.version == 'development' + uses: actions/checkout@v3 + with: + repository: MarkBind/markbind + path: markbind-cli + - name: Install markbind-cli@master + if: inputs.version == 'development' + run: | + npm i -g npm@8.3.1 + cd markbind-cli + npm run setup && npm run build:web + cd packages/cli + npm link + cd ../../.. + shell: bash + - name: Install a released version of markbind-cli + if: inputs.version != 'development' + run: | + npm install -g markbind-cli@${{ inputs.version }} + shell: bash + - name: Build site + run: | + BASEURL="--baseUrl ${{ inputs.baseUrl }}" + if [[ "${{ inputs.baseUrl }}" == "unsetFlag" ]]; then + BASEURL="" + echo "Default baseUrl to the config file attribute" + fi + cd curr-repo + markbind build ${{ inputs.rootDirectory }} ./_site \ + $BASEURL --site-config ${{ inputs.siteConfig }} + cd .. + echo "Site Built!" + shell: bash + - name: Deploy via gh-pages + if: inputs.service == 'gh-pages' + uses: peaceiris/actions-gh-pages@v3 + with: + github_token: ${{ inputs.token }} + publish_dir: ./curr-repo/_site + user_name: github-actions[bot] + user_email: 41898282+github-actions[bot]@users.noreply.github.com + keep_files: ${{ inputs.keepFiles }} + - name: Deploy via Surge.sh for normal deployment + if: inputs.service == 'surge' && inputs.purpose == 'deployment' + run: | + npm i -g surge + surge --project ./curr-repo/_site --domain ${{ inputs.domain }} + shell: bash + env: + SURGE_TOKEN: ${{ inputs.token }} + - name: Deploy via Surge.sh for PR Preview + if: inputs.service == 'surge' && inputs.purpose == 'pr-preview' && github.event_name == 'pull_request' + run: | + echo "prNum=${{ github.event.number }}" >> $GITHUB_ENV + npm i -g surge + PR_PREVIEW_URL="https://pr-${{ github.event.number }}-${{ inputs.domain }}" + echo "previewUrl=$PR_PREVIEW_URL" >> $GITHUB_ENV + surge --project ./curr-repo/_site --domain $PR_PREVIEW_URL + shell: bash + env: + SURGE_TOKEN: ${{ inputs.token }} + - name: Find existing PR preview link comment + if: inputs.service == 'surge' && inputs.purpose == 'pr-preview' && github.event_name == 'pull_request' + uses: peter-evans/find-comment@v1 + id: fc + with: + issue-number: ${{ env.prNum }} + body-includes: Your PR can be previewed + - name: Comment PR preview link in PR + if: inputs.service == 'surge' && inputs.purpose == 'pr-preview' && github.event_name == 'pull_request' && steps.fc.outputs.comment-id == 0 + uses: peter-evans/create-or-update-comment@v1 + with: + issue-number: ${{ env.prNum }} + body: | + Thank you for submitting the Pull Request! :thumbsup: + + Your PR can be previewed [here](${{ env.previewUrl }}) \ No newline at end of file diff --git a/entrypoint.sh b/entrypoint.sh deleted file mode 100644 index eddf8ae..0000000 --- a/entrypoint.sh +++ /dev/null @@ -1,22 +0,0 @@ -#!/bin/sh - -set -e - -echo '👍 MAIN ENTRYPOINT HAS STARTED—' -npm install -g markbind-cli -echo '👍 BUILDING THE SITE' -markbind build --baseUrl ${BASE_URL} -echo '👍 THE SITE IS BUILT—PUSHING IT BACK TO GITHUB-PAGES' -cd _site -remote_repo="https://x-access-token:${GITHUB_TOKEN}@github.com/${GITHUB_REPOSITORY}.git" && \ -remote_branch="gh-pages" && \ -git init && \ -git config user.name "${GITHUB_ACTOR}" && \ -git config user.email "${GITHUB_ACTOR}@users.noreply.github.com" && \ -git add . && \ -echo -n 'Files to Commit:' && ls -l | wc -l && \ -git commit -m'action build' > /dev/null 2>&1 && \ -git push --force $remote_repo master:$remote_branch > /dev/null 2>&1 && \ -rm -fr .git && \ -cd ../ -echo '👍 GREAT SUCCESS!'