Merge pull request #98 from lredoban/qr-code

Add QR code to comment

Author: rossjrw

.github/workflows/test.yml

@@ -33,52 +33,10 @@ jobs:
             - name: Run tests
               run: bash test/run-unit-tests.sh
 
-    test-comment-content:
-        name: Comment content
-        # Skip on pull_request_target if already ran via pull_request (same-repo PRs)
-        if: |
-            github.event_name != 'pull_request_target' ||
-            github.event.pull_request.head.repo.full_name != github.repository
-        runs-on: ubuntu-latest
-        steps:
-            - name: Checkout
-              uses: actions/checkout@v4
-              with:
-                  # For pull_request_target, checkout the PR head safely
-                  ref: ${{ github.event_name == 'pull_request_target' && github.event.pull_request.head.sha || github.ref }}
-
-            - name: Test deploy comment
-              env:
-                  GITHUB_ACTION_PATH: ${{ github.workspace }}
-                  umbrella_path: pr-preview
-                  pages_base_url: ""
-                  pages_base_path: ""
-                  pr_number: "12345"
-                  github_action_ref: ${{ github.ref }}
-                  github_action_repository: ${{ github.repository }}
-                  deployment_repository: test-owner/test-repo
-                  token: fake-token
-                  deprecated_custom_url: ""
-              run: bash test/integration/test-comment-content.sh deploy
-
-            - name: Test remove comment
-              env:
-                  GITHUB_ACTION_PATH: ${{ github.workspace }}
-                  umbrella_path: pr-preview
-                  pages_base_url: ""
-                  pages_base_path: ""
-                  pr_number: "12345"
-                  github_action_ref: ${{ github.ref }}
-                  github_action_repository: ${{ github.repository }}
-                  deployment_repository: test-owner/test-repo
-                  token: fake-token
-                  deprecated_custom_url: ""
-              run: bash test/integration/test-comment-content.sh remove
-
     # Integration tests require secrets, so only run when secrets are available
     integration-tests:
         name: Integration tests
-        needs: [test-unit, test-comment-content]
+        needs: [test-unit]
         # Run integration tests when:
         # 1. Push to main
         # 2. Same-repo PR (secrets available via pull_request)

README.md

@@ -7,6 +7,7 @@ Features:
 -   Creates and deploys previews of pull requests to your GitHub Pages site
 -   Leaves a comment on the pull request with a link to the preview so that you and your team can collaborate on new features faster
 -   Updates the deployment and the comment whenever new commits are pushed to the pull request
+-   Can optionally include a QR code in the preview comment for easy mobile access
 -   Cleans up after itself — removes deployed previews when the pull request is closed
 -   Can be configured to override any of these behaviours
 
@@ -21,13 +22,15 @@ Preview URLs look like this: `https://[owner].github.io/[repo]/pr-preview/pr-[nu
 
 This Action does not currently support deploying previews for PRs from forks, but will do so in [the upcoming v2](https://github.com/rossjrw/pr-preview-action/pull/6).
 
-# Usage
+# Setup
 
 A [GitHub Actions workflow](https://docs.github.com/en/actions/learn-github-actions) is required to use this Action.
 
-All the workflow needs to do first is checkout the repository and build the Pages site.
+You just need to do two things to set up your repository to support previews, both in the repository settings:
+
+### 1. Deploy Pages from branch
 
-First, ensure that your repository is configured to have its GitHub Pages site deployed from a branch, by setting the source for the deployment under **Settings** > **Pages** of your repository to **Deploy from branch**:
+Ensure that your repository is configured to have its GitHub Pages site deployed from a branch, by setting the source for the deployment under **Settings** > **Pages** of your repository to **Deploy from branch**:
 
 <p align="center">
   <img src="https://github.com/rossjrw/pr-preview-action/blob/main/.github/deployment-settings.png" alt="GitHub Pages settings">
@@ -36,7 +39,16 @@ First, ensure that your repository is configured to have its GitHub Pages site d
   Pictured: Repository Pages settings at /settings/page
 </p>
 
-The `gh-pages` branch is used for GitHub Pages deployments by convention, and will be used in examples here as well.
+> [!IMPORTANT]  
+> The other option (called "GitHub Actions") has a [misleading name](https://github.com/orgs/community/discussions/30113#discussioncomment-7650234) and does not work with this action.
+
+### 2. Let your workflow write to the repo
+
+In **Settings** > **Actions** > **General** > **Workflow permissions**, select "Read and write permissions" to allow action runs to make changes to your deployment branch (in this case, to add and remove previews).
+
+# Usage
+
+All the workflow needs to do before running the preview action is checkout the repository and build the Pages site.
 
 If your GitHub pages site is deployed from the `gh-pages` branch, built with e.g. an `npm` script to the `./build/` dir, and you're happy with the default settings, usage is very simple:
 
@@ -71,11 +83,16 @@ jobs:
               uses: rossjrw/pr-preview-action@v1
               with:
                   source-dir: ./build/
+                  preview-branch: gh-pages
+                  qr-code: true
 ```
 
+> [!TIP]  
+> The `gh-pages` branch is used for GitHub Pages deployments by convention, and will be used in examples here as well, but you can use whatever branch you like (just make sure to change the `preview-branch` input).
+
 ## Inputs (configuration)
 
-The following input parameters are provided, which can be passed to the `with` parameter. All parameters are optional and have a default value.
+The following input parameters are provided, which can be passed to the `with` parameter. ALL parameters are optional and have a default value.
 
 | Input&nbsp;parameter | Description |
 | --- | --- |
@@ -88,6 +105,7 @@ The following input parameters are provided, which can be passed to the `with` p
 | `pages-base-path` | Path that GitHub Pages is being served from, as configured in your repository settings, e.g. `docs/`. When generating the preview URL path, this is removed from the beginning of the file path. <br><br> Default: `.` (repository root) |
 | `wait-for-pages-deployment` <br> (boolean) | Whether to wait for the GitHub Pages deployment to complete. When enabled, the action will poll the GitHub Deployments API and delay workflow completion until the Pages deployment finishes, e.g. to ensure the preview URL is accessible when the comment is posted. <br><br> Default: `false` (this will be `true` in a future version of this Action) |
 | `comment` <br> (boolean) | Whether to leave a [sticky comment](https://github.com/marocchino/sticky-pull-request-comment) on the PR after the preview is built.<br> The comment may be added before the preview finishes deploying unless `wait-for-pages-deployment` is enabled. <br><br> Default: `true` |
+| `qr-code` <br> (booleanish) | Whether to include a QR code in the sticky comment for easy mobile access, which links to the preview URL. Does nothing if `comment` is `false`. <br> Set to `"true"`/`"false"` to enable/disable, or to a string to be used as a custom QR code provider ([see below](#use-a-different-qr-code-provider)). <br><br> Default: `false` |
 | `token` | Authentication token for the preview deployment. <br> The default value works for non-fork pull requests to the same repository. For anything else, you will need a [Personal Access Token](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token) with permission to access it, and [store it as a secret](https://docs.github.com/en/actions/security-guides/using-secrets-in-github-actions) in your repository. E.g. you might name that secret 'PREVIEW_TOKEN' and use it with `token: ${{ secrets.PREVIEW_TOKEN }}`. <br><br> Default: `${{ github.token }}`, which gives the action permission to deploy to the current repository. |
 | `action` <br> (enum) | Determines what this action will do when it is executed. Supported values: <br><br> <ul><li>`deploy` - create and deploy the preview, overwriting any existing preview in that location.</li><li>`remove` - remove the preview.</li><li>`auto` - determine whether to deploy or remove the preview based on [the emitted event](https://docs.github.com/en/developers/webhooks-and-events/webhooks/webhook-events-and-payloads#pull_request). If the event is `pull_request`, it will deploy the preview when the event type is `opened`, `reopened` and `synchronize`, and remove it on `closed` events. Does not do anything for other events or event types, even if you explicitly instruct the workflow to run on them.</li><li>`none` and all other values: does not do anything.</li></ul> Default: `auto` |
 
@@ -227,6 +245,7 @@ jobs:
                   action: auto
                   wait-for-pages-deployment: false
                   comment: true
+                  qr-code: false
 ```
 
 ...and an accompanying main deployment workflow:
@@ -327,6 +346,18 @@ Set `wait-for-deployment: true` to make the action automatically wait for Pages
       wait-for-pages-deployment: true
 ```
 
+### Use a different QR code provider
+
+If you have this action include a QR code in the sticky comment with `qr-code: true`, the default QR code provider is [qr.rossjrw.com](https://qr.rossjrw.com/), a provider that I built for this project because I don't trust any pre-existing ones. Likewise, you probably shouldn't trust mine - what if I go rogue and change all your QR codes to point to something else? You never know.
+
+To use a different QR code provider (I encourage you to make your own - consider forking https://github.com/rossjrw/qrcode-worker), set `qr-code` to its URL. The URI-encoded preview link will be appended to it. E.g.:
+
+```yml
+- uses: rossjrw/pr-preview-action@v1
+  with:
+      qr-code: https://my-qrcode-provider.example.com/generate?url=
+```
+
 ### Customise the sticky comment
 
 You can use `id`, `with: comment: false`, the output values and [context variables](https://docs.github.com/en/actions/reference/workflows-and-actions/contexts) to construct your own comment to be left on the PR. This example recreates this Action's default comment (complete with HTML spacing jank), but you could change it however you like, use a different commenting Action from the marketplace, etc.
@@ -365,7 +396,7 @@ jobs:
                   message: |
                       [PR Preview Action](https://github.com/rossjrw/pr-preview-action) ${{ steps.preview-step.outputs.action-version }}
                       :---:
-                      | <p></p> :rocket: View preview at <br> ${{ steps.preview-step.outputs.preview-url }} <br><br>
+                      | <p><img src="https://qr.rossjrw.com/?url=${preview_url}" height="100" align="right" alt="QR code for preview link"></p> :rocket: View preview at <br> ${{ steps.preview-step.outputs.preview-url }} <br><br>
                       | <h6>Built to branch [`${{ env.PREVIEW_BRANCH }}`](${{ github.server_url }}/${{ github.repository }}/tree/${{ env.PREVIEW_BRANCH }}) at ${{ steps.preview-step.outputs.action-start-time }}. <br> Preview will be ready when the [GitHub Pages deployment](${{ github.server_url }}/${{ github.repository }}/deployments) is complete. <br><br> </h6>
 
             - uses: marocchino/sticky-pull-request-comment@v2

action.yml

@@ -13,6 +13,7 @@ inputs:
         description: >
             The token to use for the deployment. Default is GITHUB_TOKEN in the current repository. If you need more permissions for things such as deploying to another repository, you can add a Personal Access Token (PAT).
 
+
         required: false
         default: ${{ github.token }}
     preview-branch:
@@ -39,6 +40,7 @@ inputs:
         description: >
             The PR number to use for the preview path. Defaults to the PR number from the GitHub event context. Override this for testing or when not triggered by a pull_request event.
 
+
         required: false
         default: ""
     deploy-repository:
@@ -47,18 +49,24 @@ inputs:
             
             You will need to add a Personal Access Token (PAT) in the `token` input in order to allow the action running in one repository to make changes to another repository.
 
+
         required: false
         default: ${{ github.repository }}
     wait-for-pages-deployment:
         description: >
             Whether to wait for GitHub Pages deployment before continuing, e.g. to ensure the preview URL is actually accessible when the sticky comment is posted.
 
+
         required: false
         default: "false"
     comment:
         description: Whether to leave a sticky comment on the calling PR at the end of the workflow.
         required: false
         default: "true"
+    qr-code:
+        description: Whether to display a QR code in the sticky comment.
+        required: false
+        default: "false"
     deploy-commit-message:
         description: The commit message to use when adding/updating a preview.
         required: false
@@ -89,6 +97,7 @@ inputs:
             
             If set to `auto`, the action will try to determine whether to deploy or remove the preview. It will deploy the preview on `pull_request.types.synchronize` and `.opened` events, and remove it on `pull_request.types.closed` events. It will not do anything for all other events. `auto` is the default value.
 
+
         required: false
         default: auto
 
@@ -133,11 +142,12 @@ runs:
               pages_base_url: ${{ inputs.pages-base-url }}
               pages_base_path: ${{ inputs.pages-base-path }}
               pr_number: ${{ inputs.pr-number || github.event.number }}
-              github_action_ref: ${{ github.action_ref || github.ref }}
-              github_action_repository: ${{ github.action_repository || github.repository }}
+              action_repository: ${{ github.action_repository || github.repository }}
+              action_ref: ${{ github.action_ref || github.ref }}
               deployment_repository: ${{ inputs.deploy-repository }}
               token: ${{ inputs.token }}
               deprecated_custom_url: ${{ inputs.custom-url }}
+              qr_code_wanted: ${{ inputs.qr-code }}
           run: $GITHUB_ACTION_PATH/lib/main.sh
           shell: bash
 
@@ -192,7 +202,8 @@ runs:
                 "${{ github.server_url }}" \
                 "${{ inputs.deploy-repository }}" \
                 "${{ env.action_start_time }}" \
-                "deploy")
+                "deploy" \
+                "${{ env.qr_code_provider }}")
               {
                 echo "content<<EOF"
                 echo "$CONTENT"
@@ -262,7 +273,8 @@ runs:
                 "${{ github.server_url }}" \
                 "${{ inputs.deploy-repository }}" \
                 "${{ env.action_start_time }}" \
-                "remove")
+                "remove" \
+                "${{ env.qr_code_provider }}")
               {
                 echo "content<<EOF"
                 echo "$CONTENT"

lib/generate-comment.sh

@@ -2,7 +2,6 @@
 set -euo pipefail
 
 # Generate comment content for PR preview deployment
-# Usage: generate-comment.sh <action_repository> <action_version> <preview_url> <preview_branch> <server_url> <deploy_repository> <action_start_time> <deployment_action>
 
 action_repository=${1:?missing action_repository}
 action_version=${2:?missing action_version}
@@ -12,12 +11,18 @@ server_url=${5:?missing server_url}
 deploy_repository=${6:?missing deploy_repository}
 action_start_time=${7:?missing action_start_time}
 deployment_action=${8:?missing deployment_action}
+qr_code_provider=${9:-} # falsy qr code provider means no QR code
 
 if [ "$deployment_action" = "deploy" ]; then
+    qr_code=""
+    if [ -n "$qr_code_provider" ]; then
+        qr_code="<img src=\"${qr_code_provider}${preview_url}\" height=\"100\" align=\"right\" alt=\"QR code for preview link\">"
+    fi
+
     cat << EOF
 [PR Preview Action](https://github.com/${action_repository}) ${action_version}
 :---:
-| <p></p> :rocket: View preview at <br> ${preview_url} <br><br>
+| <p>$qr_code</p> :rocket: View preview at <br> ${preview_url} <br><br>
 | <h6>Built to branch [\`${preview_branch}\`](${server_url}/${deploy_repository}/tree/${preview_branch}) at ${action_start_time}. <br> Preview will be ready when the [GitHub Pages deployment](${server_url}/${deploy_repository}/deployments) is complete. <br><br> </h6>
 EOF
 

lib/main.sh

@@ -5,7 +5,7 @@ source "$GITHUB_ACTION_PATH/lib/calculate-pages-base-url.sh"
 source "$GITHUB_ACTION_PATH/lib/remove-prefix-path.sh"
 source "$GITHUB_ACTION_PATH/lib/determine-auto-action.sh"
 
-declare deployment_action pr_number deployment_repository pages_base_url pages_base_path umbrella_path github_action_ref github_action_repository deprecated_custom_url
+declare deployment_action pr_number deployment_repository pages_base_url pages_base_path umbrella_path action_repository action_ref deprecated_custom_url qr_code_wanted
 
 # Deprecation of custom-url in favour of pages-base-url
 if [ -z "$pages_base_url" ] && [ -n "$deprecated_custom_url" ]; then
@@ -31,10 +31,21 @@ if [ "$deployment_action" = "auto" ]; then
     echo >&2 "Auto action is $deployment_action"
 fi
 
-action_version=$("$GITHUB_ACTION_PATH/lib/find-current-git-tag.sh" -p "$github_action_repository" -f "$github_action_ref")
+action_version=$("$GITHUB_ACTION_PATH/lib/find-current-git-tag.sh" -p "$action_repository" -f "$action_ref")
 action_start_timestamp=$(date '+%s')
 action_start_time=$(date '+%Y-%m-%d %H:%M %Z')
 
+if [ "$qr_code_wanted" != "false" ]; then
+    if [ "$qr_code_wanted" = "true" ]; then
+        qr_code_provider="https://qr.rossjrw.com/?color.dark=0d1117&url="
+    else
+        qr_code_provider="$qr_code_wanted"
+    fi
+    echo >&2 "Using QR code provider: $qr_code_provider<URL>"
+else
+    qr_code_provider=""
+fi
+
 # Export variables for later use by this action
 {
     echo "empty_dir_path=$(mktemp -d)"
@@ -45,9 +56,11 @@ action_start_time=$(date '+%Y-%m-%d %H:%M %Z')
     echo "preview_url_path=$preview_url_path"
     echo "preview_url=https://$pages_base_url/$preview_url_path/"
 
-    echo "action_repository=$github_action_repository"
+    echo "action_repository=$action_repository"
     echo "action_version=$action_version"
     echo "action_start_time=$action_start_time"
+
+    echo "qr_code_provider=$qr_code_provider"
 } >> "$GITHUB_ENV"
 
 # Export variables for use by later actions in user workflow