Is there an easy way to preview the new article?

[f-hollow]

Originally posted by @tore-espressif in https://github.com/espressif/developer-portal/issues/37#issuecomment-2189391818

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.

```yml # 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].

```yml - 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