search

espressif / developer-portal

Developer Portal
https://developer.espressif.com
MIT License
6 stars 10 forks source link

Is there an easy way to preview the new article? #43

Open f-hollow opened 1 month ago

f-hollow commented 1 month ago

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:

f-hollow commented 3 weeks ago

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 commented 1 week ago

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 commented 1 week ago

@hfudev also shared this:

Worth checking:

Accepting fork PRs can pose security threats:

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