Provide a live preview for contributions done from fork repo

[tbouffard]

ℹ️ Part of a top-level initiative: #670

Currently, the preview is built and only attached as an artifact of the GH Actions run. It is not deployed to surge, so there is no live environment available.
Be also aware of #402.

Current limitations

• not supported by the surge-preview action
• we cannot use pull_request_target for security reason: we are checkouting code from untrusted users to build the site which may be subject to malicious manipulation. See https://securitylab.github.com/research/github-actions-preventing-pwn-requests/

Resources

• Can't use surge-preview for pull-request afc163/surge-preview#124
• Preview comment not being added + CI failing afc163/surge-preview#212 (comment)
• Resolve GitHub Action Permissions -- Error: Resource not accessible by integration afc163/surge-preview#248 (comment)

Possible solutions

• to review: https://michaelheap.com/access-secrets-from-forks/
  • present a way to use pull_request_target more safely
  • also provide actions that let knows the permission of a gh_token which may help in various situation (including bonitasoft/action, see pr-title-conventional-commits: create PR comment only if permissions are properly set actions#93)
• manage the preview with dedicated workflow, in several step involving build site in a workflow and deploy in a workflow triggered by workflow_run
  • PR comment for "in progress" https://github.com/ant-design/ant-design-pro/blob/v6.0.0-beta.1/.github/workflows/preview-start.yml
  • https://github.com/ant-design/ant-design-pro/blob/v6.0.0-beta.1/.github/workflows/preview-build.yml
  • https://github.com/ant-design/ant-design-pro/blob/v6.0.0-beta.1/.github/workflows/preview-deploy.yml
• Make the surge-preview action correctly detects the pr number in a workflow_run and provide a solutions with several workflows (as in the solution just described above this line)

Investigations

See #686 (comment). It also includes next steps.

[tbouffard]

Investigations done in week 2024-04-17

Work done with @benjaminParisel

All tests have been done in the https://github.com/process-analytics/github-actions-playground/ repository with a fake site.

Experiment a solution with 2 steps as described in https://securitylab.github.com/research/github-actions-preventing-pwn-requests/

• first step build the site and upload an artifact (pull_request event)
• 2nd step (workflow_run event). The current implementation of the surge-preview action wasn't able to detect the PR number in this case. We have experiment a fix in fix: correctly detect PR number when run with workflow_run benjaminParisel/surge-preview#1

This custom implementation has been tested in a PR created from a fork repo, see process-analytics/github-actions-playground#349. It has also been tested with PR created from the target repository, see process-analytics/github-actions-playground#350.

We have checked that the teardown could be managed in a specific workflow like in process-analytics/github-actions-playground#351

A contribution has been proposed to the official surge-preview action afc163/surge-preview#294 which is based on our experiment.

Next steps

To have a fully working solution

• use the official surge-preview (or our own fork) including the proposed fix
• decide if we want to manage the teardown in each PR. We have an workflow in the documentation-site repo that teardown old deployments --> decision: no, this simplifies the maintenance;
• update our surge-preview-tools (in the bonitasoft/actions repo) action to make it support workflow_run to get the PR number (same implementation as in the proposed fix) (see feat(surge-preview): add support of workflow_run event actions#131)
• validate that the 2 steps build/deploy reusable workflows work. See ci: test the new surge preview deployment [POC] #703
  • Notice that currently, the site is already uploaded as a workflow artifact. However, it doesn't use a fixed name. It currently include a part which relates to the job id. This is required when the action that build the site is used in the documentation-site repository: they are 2 jobs in the same workflow which upload the artifact so they cannot have the same name, see ci: bump actions used in composite actions #676.
  • This will require that the documentation-site repository provides new shared actions or reusable workflows (see Convert build/publish preview actions to reusable workflow #700) to manage the multi-steps solutions (build then deploy, then create a PR comment with the details of changes). Currently, it provides a single actions that manages everything. See also Convert build/publish preview actions to reusable workflow #700.
• Manage PR content links in a dedicated reusable workflow: ci: create reusable workflow to comment PR about changes #715
  • This provides a better separation of concerns.
  • It also allows direct use of the existing custom action to be executed in a pull_request event context.
  • This will require managing an additional workflow in all content repositories, which will increase maintenance a little, but using a “reusable workflow” will limit the cost (mainly the cost at installation time).
  • It will be called in workflows triggered by the pull_request_target event (there is no build but only a check of files modified by the PR).
• do tests to build the site in a documentation content repository (for example, with labs): ci: Use reusable workflow bonita-labs-doc#159 + test with ci: update job id for validate content bonita-labs-doc#160
• Apply the changes to all content repositories
  • bonita-doc ci: use reusable workflows bonita-doc#2727
  • bcd ci: use reusable workflows bonita-continuous-delivery-doc#226
  • bpi ci: deploy preview for PR created from fork repo bonita-process-insights-doc#4
  • central ci: use reusable workflows bonita-central-doc#35
  • cloud ci: use reusable workflows bonita-cloud-doc#60
  • test-toolkit ci: use reusable workflows bonita-test-toolkit-doc#60

[tbouffard]

All tasks are completed, so closing