diff --git a/README.md b/README.md index 5b5dfe7..1ab865c 100644 --- a/README.md +++ b/README.md @@ -29,7 +29,7 @@ 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 +# Usage A [GitHub Actions workflow](https://docs.github.com/en/actions/learn-github-actions) is @@ -89,39 +89,70 @@ jobs: source-dir: ./build/ ``` -### Important things to be aware of +## Inputs (configuration) -#### Run only when files are changed +The following input parameters are provided, which can be passed to the `with` parameter. All parameters are optional and have a default value. -Consider limiting this workflow to run [only when relevant files are -edited](https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#onpushpull_requestpull_request_targetpathspaths-ignore) -to avoid deploying previews unnecessarily. +Input parameter | Description +--- | --- +`source-dir` | When creating or updating a preview, the path to the directory that contains the files to deploy. E.g. if your project builds to `./dist/` you would put `./dist/` (or `dist`, etc.).
Equivalent to [JamesIves/github-pages-deploy-action](https://github.com/JamesIves/github-pages-deploy-action) 'folder' setting.

Default: `.` (repository root) +`deploy-repository` | The repository to deploy the preview to.
__Note:__ The `token` parameter must also be set if changing this from the default.

Default: The pull request's target repository. +`preview-branch` | Branch to save previews to. This should be the same branch that your GitHub Pages site is deployed from.

Default: `gh-pages` +`umbrella-dir` | Path to the directory to place previews in.
The umbrella directory is used to namespace previews from your main branch's deployment on GitHub Pages.

Default: `pr-preview` +`pages-base-url` | Base URL to use when providing a link to the preview site.

Default: The pull request's target repository's default GitHub Pages URL (e.g. `rossjrw.github.io/pr-preview-action/`) +`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.

Default: `.` (repository root) +`comment`
(boolean) | Whether to leave a [sticky comment](https://github.com/marocchino/sticky-pull-request-comment) on the PR after the preview is built.
The comment may be added before the preview finishes deploying.

Default: `true` +`token` | Authentication token for the preview deployment.
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 }}`.

Default: `${{ github.token }}`, which gives the action permission to deploy to the current repository. +`action`
(enum) | Determines what this action will do when it is executed. Supported values:

Default: `auto` -#### Run on all appropriate pull request events +## Outputs -Be sure to [pick the right event -types](https://docs.github.com/en/actions/using-workflows/events-that-trigger-workflows#pull_request) -for the `pull_request` event. It only comes with `opened`, `reopened`, and -`synchronize` by default — but this Action assumes by default that -the preview should be removed during the `closed` event, which it only sees -if you explicitly add it to the workflow. +Several output values are provided to use after this Action in your workflow. To use them, give this Action's step an `id` and reference the value with `${{ steps..outputs. }}`, e.g.: -#### Grant Actions permission to read and write to the repository +```yml +# .github/workflows/preview.yml +jobs: + deploy-preview: + steps: + - uses: rossjrw/pr-preview-action@v1 + id: preview-step + - if: steps.preview-step.outputs.deployment-action == "deploy" + run: echo "Preview visible at ${{ steps.preview-step.outputs.preview-url }}" +``` + +You could use these outputs and input parameter `comment: false` to write your own sticky comment after the Action has run. + +Output | Description +--- | --- +`deployment-action` | Resolved value of the `action` input parameter (deploy, remove, none). +`pages-base-url` | What this Action thinks the base URL of the GitHub Pages site is. +`preview-url-path` | Path to the preview from the Pages base URL. +`preview-url` | Full URL to the preview (`https:////`). +`action-version` | The version of this Action when it was run. +`action-start-timestamp` | The time that the workflow step started as a Unix timestamp. +`action-start-time` | The time that the workflow step started in a readable format (UTC, depending on runner). + +# Considerations + +## Common pitfalls + +### Grant Actions permission to read and write to the repository This must be changed in the repository settings by selecting "Read and write permissions" at **Settings** > **Actions** > **General** > **Workflow permissions**. Otherwise, the Action won't be able to make any changes to your deployment branch. -#### Set a concurrency group +### Run on all appropriate pull request events -I highly recommend [setting a concurrency -group](https://docs.github.com/en/actions/using-jobs/using-concurrency) -scoped to each PR using `github.ref` as above, which should prevent the -preview and comment from desynchronising if you are e.g. committing very -frequently. +Be sure to [pick the right event +types](https://docs.github.com/en/actions/using-workflows/events-that-trigger-workflows#pull_request) +for the `pull_request` event. It only comes with `opened`, `reopened`, and +`synchronize` by default — but this Action assumes by default that +the preview should be removed during the `closed` event, which it only sees +if you explicitly add it to the workflow. -#### Ensure your main deployment is compatible +### Ensure your main deployment is compatible If you are using GitHub Actions to deploy your GitHub Pages sites (typically on push to the main branch), there are some actions you should @@ -161,11 +192,11 @@ vice-versa. all files in the deployment location. This will destroy any ongoing preview deployments. Instead, consider adjusting your deployment workflow to rebase or merge your main deployment onto the deployment - branch such that it respects other ongoing deployments. + branch to respect other ongoing deployments. For example, if you are using [JamesIves/github-pages-deploy-action](https://github.com/JamesIves/github-pages-deploy-action) - to deploy your build, be aware that at the time of writing (v4.3.0) it + to deploy your build, be aware that at the time of writing (v4.7.2) it force-pushes new deployments by default. You can disable this by setting its `force` parameter to `false`, which will prompt it to rebase new deployments instead of force-pushing them: @@ -183,92 +214,21 @@ vice-versa. This feature was introduced in v4.3.0 of the above Action. -#### +## Best practices -## Configuration +### Run only when files are changed -The following configuration settings are provided, which can be passed to -the `with` parameter. - -- `source-dir`: Directory containing files to deploy. - - E.g. if your project builds to `./dist/` you would put `./dist/` (or just - `dist`) here. For the root directory of your project, put `.` here. - - Equivalent to - [JamesIves/github-pages-deploy-action](https://github.com/JamesIves/github-pages-deploy-action) - 'folder' setting. - - Will be ignored when removing a preview. - - Default: `.` - -- `preview-branch`: Branch on which the previews will be deployed. This - should be the same branch that your GitHub Pages site is deployed from. - - Default: `gh-pages` - -- `umbrella-dir`: Name of the directory containing all previews. All - previews will be created inside this directory. - - The umbrella directory is used to namespace previews from your main - branch's deployment on GitHub Pages. - - Set to `.` to place preview directories into the root directory, but be - aware that this may cause your main branch's deployment to interfere with - your preview deployments (and vice-versa!) - - Default: `pr-preview` - -- `pages-base-path`: Path that GitHub Pages is being served from, as configured in your repository settings. When generating the preview URL, this is removed from the beginning of the path. - - Default: ` ` (repository root) - -- `custom-url`: Base URL to use when providing a link to the preview site. - - Default: Will attempt to calculate the repository's GitHub Pages URL - (e.g. "rossjrw.github.io"). - -- `deploy-repository`: The repository to deploy the preview to. - - If this value is changed from the default, the `token` parameter must also - be set (see below). - - Default: The current repository that the pull request was made in. - -- `token`: The token to use for the preview deployment. The default value is - fine for deployments to the current repository, but if you want to deploy - the preview to a different repository (see `deploy-repository` above), you - will need to create 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 }}`. - - Default: `${{ github.token }}`, which gives the action permission to - deploy to the current repository. - -- **(Advanced)** `action`: Determines what this action will do when it is - executed. Supported values: `deploy`, `remove`, `none`, `auto`. - - - `deploy`: will attempt to deploy the preview and overwrite any - existing preview in that location. - - `remove`: will attempt to remove the preview in that location. - - `auto`: the action will try to 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). - It will deploy the preview on `pull_request.types.opened`, `.reopened` - and `.synchronize` events; and remove it on `pull_request.types.closed` - events. It will not do anything for all other events, even if you - explicitly specify that the workflow should run on them. - - `none` and all other values: the action will not do anything. - - Default value: `auto` +Consider limiting this workflow to run [only when relevant files are +edited](https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#onpushpull_requestpull_request_targetpathspaths-ignore) +to avoid deploying previews unnecessarily. -## Outputs +### Set a concurrency group -- `deployment-url`: the URL at which the preview has been deployed. +I highly recommend [setting a concurrency +group](https://docs.github.com/en/actions/using-jobs/using-concurrency) +scoped to each PR using `github.ref` as above, which should prevent the +preview and comment from desynchronising if you are e.g. committing very +frequently. ## Examples @@ -394,13 +354,11 @@ jobs: action: deploy ``` -## Acknowledgements +# Acknowledgements Big thanks to the following: -- [shlinkio/deploy-preview-action](https://github.com/shlinkio/deploy-preview-action) - (MIT), prior art that informed the direction of this Action -- [JamesIves/github-pages-deploy-action](https://github.com/JamesIves/github-pages-deploy-action) - (MIT), used by this Action to deploy previews -- [marocchino/sticky-pull-request-comment](https://github.com/marocchino/sticky-pull-request-comment) - (MIT), used by this Action to leave a sticky comment on pull requests +- [shlinkio/deploy-preview-action](https://github.com/shlinkio/deploy-preview-action) (MIT), prior art that informed the direction of this Action +- [JamesIves/github-pages-deploy-action](https://github.com/JamesIves/github-pages-deploy-action) (MIT), used by this Action to deploy previews +- [marocchino/sticky-pull-request-comment](https://github.com/marocchino/sticky-pull-request-comment) (MIT), used by this Action to leave a sticky comment on pull requests +- [Everyone who has contributed](https://github.com/rossjrw/pr-preview-action/graphs/contributors) to this Action diff --git a/action.yml b/action.yml index bf291a3..8637d86 100644 --- a/action.yml +++ b/action.yml @@ -22,9 +22,13 @@ inputs: required: false default: gh-pages umbrella-dir: - description: Name of the directory containing all previews. + description: Path to the directory containing all previews. required: false default: pr-preview + pages-base-url: + description: URL of the repo's GitHub Pages site. + required: false + default: "" pages-base-path: description: Path that GitHub Pages is served from. required: false @@ -45,8 +49,14 @@ inputs: to another repository. required: false default: ${{ github.repository }} + comment: + description: Whether to leave a sticky comment on the calling PR. + required: false + default: "true" + custom-url: - description: Custom pages URL + description: Deprecated, use `pages-base-url` instead. + deprecationMessage: Use `pages-base-url` instead. required: false default: "" action: @@ -69,134 +79,99 @@ inputs: default: auto outputs: + deployment-action: + description: Resolved value of the 'action' input parameter (deploy, remove, none). + value: ${{ steps.setup.outputs.deployment_action }} + pages-base-url: + description: What this Action thinks the base URL of the GitHub Pages site is. + value: ${{ steps.setup.outputs.pages_base_url }} + preview-url-path: + description: Path to the preview from the Pages base URL. + value: ${{ steps.setup.outputs.preview_url_path }} + preview-url: + description: Full URL to the preview (https://[pages-base-url]/[preview-url-path]/). + value: ${{ steps.setup.outputs.preview_url }} + action-version: + description: The version of this Action when it was run. + value: ${{ steps.setup.outputs.action_version }} + action-start-timestamp: + description: The Unix timestamp that the action started. + value: ${{ steps.setup.outputs.action_start_timestamp }} + action-start-time: + description: The time that the action started in a readable format (UTC, depending on runner). + value: ${{ steps.setup.outputs.action_start_time }} + deployment-url: - description: The URL at which the preview has been deployed - value: ${{ steps.url.outputs.url }} + description: Deprecated, use `preview-url` instead. + value: ${{ steps.setup.outputs.preview_url }} runs: using: composite steps: - - name: Store environment variables + - name: Setup preview environment + id: setup env: - action: ${{ inputs.action }} - umbrella: ${{ inputs.umbrella-dir }} - pagesbase: ${{ inputs.pages-base-path }} - pr: ${{ github.event.number }} - actionref: ${{ github.action_ref }} - actionrepo: ${{ github.action_repository }} - customurl: ${{ inputs.custom-url }} - deployrepo: ${{ inputs.deploy-repository }} + deployment_action: ${{ inputs.action }} + umbrella_path: ${{ inputs.umbrella-dir }} + pages_base_url: ${{ inputs.pages-base-url }} + pages_base_path: ${{ inputs.pages-base-path }} + pr_number: ${{ github.event.number }} + github_action_ref: ${{ github.action_ref }} + github_action_repository: ${{ github.action_repository }} + deployment_repository: ${{ inputs.deploy-repository }} token: ${{ inputs.token }} - run: | - echo "action=$action" >> $GITHUB_ENV - echo "pr=$pr" >> $GITHUB_ENV - - repo_org=$(echo "$deployrepo" | cut -d "/" -f 1) - repo_name=$(echo "$deployrepo" | cut -d "/" -f 2) - - if [ ! -z "$customurl" ]; then - pagesurl="$customurl" - elif [ "${repo_org}.github.io" == "$repo_name" ]; then - pagesurl="${repo_org}.github.io" - else - pagesurl=$(echo "$deployrepo" | sed 's/\//.github.io\//') - fi - - echo "pagesurl=$pagesurl" >> $GITHUB_ENV - - targetdir="$umbrella/pr-$pr" - echo "targetdir=$targetdir" >> $GITHUB_ENV - - pagespath=$("$GITHUB_ACTION_PATH/lib/remove-prefix-path.sh" -b "$pagesbase" -o "$targetdir") - if [ -n "$pagesbase" ] && [ "$("$GITHUB_ACTION_PATH/lib/remove-prefix-path.sh" -b "" -o "$targetdir")" = "$pagespath" ]; then - echo "::warning title=pages-base-path doesn't match::pages-base-path directory ($pagesbase) does not contain umbrella-dir ($umbrella). pages-base-path has been ignored." - pagespath=$targetdir - fi - echo "pagespath=$pagespath" >> $GITHUB_ENV - - echo "emptydir=$(mktemp -d)" >> $GITHUB_ENV - echo "datetime=$(date '+%Y-%m-%d %H:%M %Z')" >> $GITHUB_ENV - - echo "actionref=$actionref" >> $GITHUB_ENV - echo "actionrepo=$actionrepo" >> $GITHUB_ENV - echo "deployrepo=$deployrepo" >> $GITHUB_ENV - echo "token=$token" >> $GITHUB_ENV - shell: bash - - - name: Determine action version - run: | - action_version=$("$GITHUB_ACTION_PATH/lib/find-current-git-tag.sh" -p $actionrepo -f $actionref) - echo "action_version=$action_version" >> "$GITHUB_ENV" - shell: bash - - - name: Determine auto action - if: env.action == 'auto' - run: $GITHUB_ACTION_PATH/lib/determine-auto-action.sh + deprecated_custom_url: ${{ inputs.custom-url }} + run: $GITHUB_ACTION_PATH/lib/main.sh shell: bash - name: Deploy preview directory - if: env.action == 'deploy' + if: env.deployment_action == 'deploy' uses: JamesIves/github-pages-deploy-action@65b5dfd4f5bcd3a7403bbc2959c144256167464e # v4.5.0 with: - token: ${{ env.token }} - repository-name: ${{ env.deployrepo }} + token: ${{ inputs.token }} + repository-name: ${{ inputs.deploy-repository }} branch: ${{ inputs.preview-branch }} folder: ${{ inputs.source-dir }} - target-folder: ${{ env.targetdir }} - commit-message: Deploy preview for PR ${{ env.pr }} 🛫 + target-folder: ${{ env.preview_file_path }} + commit-message: Deploy preview for PR ${{ github.event.number }} 🛫 force: false - - name: Expose deployment URL - id: url - run: echo "url=https://${{ env.pagesurl }}/${{ env.pagespath }}/" >> $GITHUB_OUTPUT - shell: bash - - name: Leave a comment after deployment - if: env.action == 'deploy' && env.deployment_status == 'success' + if: | + env.deployment_action == 'deploy' && + env.deployment_status == 'success' && + (inputs.comment == 'true' || inputs.comment == true) uses: marocchino/sticky-pull-request-comment@331f8f5b4215f0445d3c07b4967662a32a2d3e31 # v2.9.0 with: header: pr-preview - message: "\ - [PR Preview Action]\ - (https://github.com/${{ env.actionrepo }}) - ${{ env.action_version }} - + message: | + [PR Preview Action](https://github.com/${{ env.action_repository }}) ${{ env.action_version }} :---: - - :rocket: Deployed preview to - https://${{ env.pagesurl }}/${{ env.pagespath }}/ - - on branch [`${{ inputs.preview-branch }}`](\ - ${{ github.server_url }}/${{ env.deployrepo }}\ - /tree/${{ inputs.preview-branch }}) - at ${{ env.datetime }} - " + |

:rocket: View preview at
${{ env.preview_url }}

+ |
Built to branch [`${{ inputs.preview-branch }}`](${{ github.server_url }}/${{ inputs.deploy-repository }}/tree/${{ inputs.preview-branch }}) at ${{ env.action_start_time }}.
Preview will be ready when the [GitHub Pages deployment](${{ github.server_url }}/${{ inputs.deploy-repository }}/deployments) is complete.

- name: Remove preview directory - if: env.action == 'remove' + if: env.deployment_action == 'remove' uses: JamesIves/github-pages-deploy-action@65b5dfd4f5bcd3a7403bbc2959c144256167464e # v4.5.0 with: - token: ${{ env.token }} - repository-name: ${{ env.deployrepo }} + token: ${{ inputs.token }} + repository-name: ${{ inputs.deploy-repository }} branch: ${{ inputs.preview-branch }} - folder: ${{ env.emptydir }} - target-folder: ${{ env.targetdir }} - commit-message: Remove preview for PR ${{ env.pr }} 🛬 + folder: ${{ env.empty_dir_path }} + target-folder: ${{ env.preview_file_path }} + commit-message: Remove preview for PR ${{ github.event.number }} 🛬 force: false - name: Leave a comment after removal - if: env.action == 'remove' && env.deployment_status == 'success' + if: | + env.deployment_action == 'remove' && + env.deployment_status == 'success' && + (inputs.comment == 'true' || inputs.comment == true) uses: marocchino/sticky-pull-request-comment@331f8f5b4215f0445d3c07b4967662a32a2d3e31 # v2.9.0 with: header: pr-preview - message: "\ - [PR Preview Action]\ - (https://github.com/${{ env.actionrepo }}) - ${{ env.action_version }} - + message: | + [PR Preview Action](https://github.com/${{ env.action_repository }}) ${{ env.action_version }} :---: - Preview removed because the pull request was closed. - - ${{ env.datetime }} - " + ${{ env.action_start_time }} diff --git a/lib/determine-auto-action.sh b/lib/determine-auto-action.sh index 55d16d9..1a2348c 100755 --- a/lib/determine-auto-action.sh +++ b/lib/determine-auto-action.sh @@ -1,28 +1,28 @@ #!/usr/bin/env bash case $GITHUB_EVENT_NAME in - "pull_request" | "pull_request_target") - echo "event_name is $GITHUB_EVENT_NAME; proceeding" - ;; - *) - echo "unknown event $GITHUB_EVENT_NAME; no action to take" - echo "action=none" >> "$GITHUB_ENV" - exit 0 - ;; +"pull_request" | "pull_request_target") + echo >&2 "event_name is $GITHUB_EVENT_NAME; proceeding" + ;; +*) + echo >&2 "unknown event $GITHUB_EVENT_NAME; no action to take" + echo "none" + exit 0 + ;; esac event_type=$(jq -r ".action" "$GITHUB_EVENT_PATH") -echo "event_type is $event_type" +echo >&2 "event_type is $event_type" case $event_type in - "opened" | "reopened" | "synchronize") - echo "action=deploy" >> "$GITHUB_ENV" - ;; - "closed") - echo "action=remove" >> "$GITHUB_ENV" - ;; - *) - echo "unknown event type $event_type; no action to take" - echo "action=none" >> "$GITHUB_ENV" - ;; +"opened" | "reopened" | "synchronize") + echo "deploy" + ;; +"closed") + echo "remove" + ;; +*) + echo >&2 "unknown event type $event_type; no action to take" + echo "none" + ;; esac diff --git a/lib/main.sh b/lib/main.sh new file mode 100755 index 0000000..c780050 --- /dev/null +++ b/lib/main.sh @@ -0,0 +1,66 @@ +#!/usr/bin/env bash + +declare deployment_action pr_number deployment_repository pages_base_url pages_base_path umbrella_path github_action_ref github_action_repository deprecated_custom_url + +# Deprecation of custom-url in favour of pages-base-url +if [ -z "$pages_base_url" ] && [ -n "$deprecated_custom_url" ]; then + pages_base_url=$deprecated_custom_url +fi + +# If pages_base_url was not set by the user, try to guess +if [ -z "$pages_base_url" ]; then + # Either .github.io or .github.io/repo + repo_org=$(echo "$deployment_repository" | cut -d "/" -f 1) + repo_name=$(echo "$deployment_repository" | cut -d "/" -f 2) + if [ "$repo_name" = "${repo_org}.github.io" ]; then + pages_base_url="${repo_org}.github.io" + else + pages_base_url=$(echo "$deployment_repository" | sed -e 's/\//.github.io\//') + fi +fi + +preview_file_path="$umbrella_path/pr-$pr_number" + +preview_url_path=$("$GITHUB_ACTION_PATH/lib/remove-prefix-path.sh" -b "$pages_base_path" -o "$preview_file_path") +if [ -n "$pages_base_path" ] && [ "$("$GITHUB_ACTION_PATH/lib/remove-prefix-path.sh" -b "" -o "$preview_file_path")" = "$preview_url_path" ]; then + echo "::warning title=pages-base-path doesn't match::The pages-base-path directory ($pages_base_path) does not contain umbrella-dir ($umbrella_path). pages-base-path has been ignored. The value of umbrella-dir should start with the value of pages-base-path." + preview_url_path=$preview_file_path +fi + +if [ "$deployment_action" = "auto" ]; then + echo >&2 "Determining auto action" + deployment_action=$("$GITHUB_ACTION_PATH/lib/determine-auto-action.sh") + 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_start_timestamp=$(date '+%s') +action_start_time=$(date '+%Y-%m-%d %H:%M %Z') + +# Export variables for later use by this action +{ + echo "empty_dir_path=$(mktemp -d)" + echo "deployment_action=$deployment_action" + + echo "preview_file_path=$preview_file_path" + echo "pages_base_url=$pages_base_url" + 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_version=$action_version" + echo "action_start_time=$action_start_time" +} >>"$GITHUB_ENV" + +# Export variables for use by later actions in user workflow +{ + echo "deployment_action=$deployment_action" + + echo "pages_base_url=$pages_base_url" + echo "preview_url_path=$preview_url_path" + echo "preview_url=https://$pages_base_url/$preview_url_path/" + + echo "action_version=$action_version" + echo "action_start_timestamp=$action_start_timestamp" + echo "action_start_time=$action_start_time" +} >>"$GITHUB_OUTPUT"