Is there an easy way to preview the new article?

[f-hollow]

Originally posted by @tore-espressif in #37 (comment)

As of now the only way to preview a new article in a PR is:

1. Check out the pull request locally.
2. Make sure you have Hugo installed locally and, in the repo folder, run hugo server.

Automate the preview process by building the PR branch with Hugo and deploying it using GitHub Actions:

• How to automate previews for Github Pages
• Using GitHub Actions to build automagic Hugo previews of draft articles

[f-hollow]

Summary

The standard page_url for a repo is <username>.github.io/<reponame>. Changing this page_url is not supported, which means that you cannot publish more than one branch from the same repo to githuab pages. I tried two workarounds without luck. Probably, there are more, but these are still workarounds for now. Also, there is a feature request: Deploy preview option for PRs that seems to be dormant.

Details

To make preview useful, we should be able to change page_url, so that we can have multiple versions of the portal for different PRs.

The standard deployment action actions/deploy-pages, can only publish to a standard URL <username>.github.io/<reponame>. The proposed workaround does not work.

# Sample workflow for building and deploying a Hugo site to GitHub Pages
name: Deploy Hugo site to Pages

on:
  # Runs on pushes targeting the default branch
  push:
    branches:
      - main

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

# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
permissions:
  contents: read
  pages: write
  id-token: write

# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
concurrency:
  group: "pages"
  cancel-in-progress: false

# Default to bash
defaults:
  run:
    shell: bash

jobs:
  # Build job
  build:
    runs-on: ubuntu-latest
    env:
      HUGO_VERSION: 0.128.0
    steps:
      - name: Install Hugo CLI
        run: |
          wget -O ${{ runner.temp }}/hugo.deb https://github.com/gohugoio/hugo/releases/download/v${HUGO_VERSION}/hugo_extended_${HUGO_VERSION}_linux-amd64.deb \
          && sudo dpkg -i ${{ runner.temp }}/hugo.deb
      - name: Checkout
        uses: actions/checkout@v4
        with:
          submodules: recursive
          fetch-depth: 0

      - name: Setup Pages
        id: pages
        uses: actions/configure-pages@v5
      - name: Install Node.js dependencies
        run: "[[ -f package-lock.json || -f npm-shrinkwrap.json ]] && npm ci || true"
      - name: Build with Hugo
        env:
          HUGO_CACHEDIR: ${{ runner.temp }}/hugo_cache
          HUGO_ENVIRONMENT: production
        run: |
          hugo \
            --gc \
            --minify \
            --baseURL "${{ steps.pages.outputs.base_url }}/"
      - name: Upload artifact
        uses: actions/upload-pages-artifact@v3
        with:
          path: ./public

  # Deployment job
  deploy:
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    runs-on: ubuntu-latest
    needs: build
    steps:
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v4

The alternative action actions-gh-pages, does not work. I tried changing branches, and I always get remote: Permission to <username>/developer-portal.git denied to github-actions[bot].

      - name: Deploy
        uses: peaceiris/actions-gh-pages@v4
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./public

[igrr]

We can probably use preview-docs.espressif.com for this. For a PR, an action would build the site and SCP it over to preview-docs.

This would probably be limited to authors who can push branches directly to this repo. It wouldn't work if a PR is done from a fork, because the forked repository wouldn't have access to secrets (e.g. SSH keys) required for deployment. Still, we could add all the regular authors here as contributors and at least for them, the workflow would be simplified.

[f-hollow]

@hfudev also shared this:

Worth checking:

• GitHub action: Deploy PR Preview
  • Downside of this project it that, it only support "branch pr", not "fork pr"
• Netlify's Deploy Preview
  • To enable "full preview" for fork pr, use netlify instead

Accepting fork PRs can pose security threats:

• Github Actions and the threat of malicious pull requests
• Why doesn't PR Preview Action support preview from forks?

---

We can try Netlify and see if it introduces any vulnerabilities. If yes, we can go with either Deploy PR Preview or preview-docs.espressif.com suggested by @igrr

[f-hollow]

Another interesting approach:

https://stackoverflow.com/questions/70620223/deploying-hugo-onto-staging-website-from-feature-branch