Skip to content

Commit df22037

Browse files
rossjrwrossjrw
authored
Merge pull request #97 from rossjrw/comment-customisation
Comment customisation
2 parents 85ebedd + 9029298 commit df22037

File tree

4 files changed

+229
-230
lines changed

4 files changed

+229
-230
lines changed

‎README.md

Lines changed: 70 additions & 112 deletions
Original file line numberDiff line numberDiff line change
@@ -29,7 +29,7 @@ This Action does not currently support deploying previews for PRs from forks,
2929
but will do so in [the upcoming
3030
v2](https://github.com/rossjrw/pr-preview-action/pull/6).
3131

32-
## Usage
32+
# Usage
3333

3434
A [GitHub Actions
3535
workflow](https://docs.github.com/en/actions/learn-github-actions) is
@@ -89,39 +89,70 @@ jobs:
8989
source-dir: ./build/
9090
```
9191
92-
### Important things to be aware of
92+
## Inputs (configuration)
9393
94-
#### Run only when files are changed
94+
The following input parameters are provided, which can be passed to the `with` parameter. All parameters are optional and have a default value.
9595

96-
Consider limiting this workflow to run [only when relevant files are
97-
edited](https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#onpushpull_requestpull_request_targetpathspaths-ignore)
98-
to avoid deploying previews unnecessarily.
96+
Input parameter | Description
97+
--- | ---
98+
`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.). <br> Equivalent to [JamesIves/github-pages-deploy-action](https://github.com/JamesIves/github-pages-deploy-action) 'folder' setting. <br><br> Default: `.` (repository root)
99+
`deploy-repository` | The repository to deploy the preview to. <br> __Note:__ The `token` parameter must also be set if changing this from the default. <br><br> Default: The pull request's target repository.
100+
`preview-branch` | Branch to save previews to. This should be the same branch that your GitHub Pages site is deployed from. <br><br> Default: `gh-pages`
101+
`umbrella-dir` | Path to the directory to place previews in. <br> The umbrella directory is used to namespace previews from your main branch's deployment on GitHub Pages. <br><br> Default: `pr-preview`
102+
`pages-base-url` | Base URL to use when providing a link to the preview site. <br><br> Default: The pull request's target repository's default GitHub Pages URL (e.g. `rossjrw.github.io/pr-preview-action/`)
103+
`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)
104+
`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. <br><br> Default: `true`
105+
`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.
106+
`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`
99107

100-
#### Run on all appropriate pull request events
108+
## Outputs
101109

102-
Be sure to [pick the right event
103-
types](https://docs.github.com/en/actions/using-workflows/events-that-trigger-workflows#pull_request)
104-
for the `pull_request` event. It only comes with `opened`, `reopened`, and
105-
`synchronize` by default &mdash; but this Action assumes by default that
106-
the preview should be removed during the `closed` event, which it only sees
107-
if you explicitly add it to the workflow.
110+
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.<id>.outputs.<name> }}`, e.g.:
108111

109-
#### Grant Actions permission to read and write to the repository
112+
```yml
113+
# .github/workflows/preview.yml
114+
jobs:
115+
deploy-preview:
116+
steps:
117+
- uses: rossjrw/pr-preview-action@v1
118+
id: preview-step
119+
- if: steps.preview-step.outputs.deployment-action == "deploy"
120+
run: echo "Preview visible at ${{ steps.preview-step.outputs.preview-url }}"
121+
```
122+
123+
You could use these outputs and input parameter `comment: false` to write your own sticky comment after the Action has run.
124+
125+
Output | Description
126+
--- | ---
127+
`deployment-action` | Resolved value of the `action` input parameter (deploy, remove, none).
128+
`pages-base-url` | What this Action thinks the base URL of the GitHub Pages site is.
129+
`preview-url-path` | Path to the preview from the Pages base URL.
130+
`preview-url` | Full URL to the preview (`https://<pages-base-url>/<preview-url-path>/`).
131+
`action-version` | The version of this Action when it was run.
132+
`action-start-timestamp` | The time that the workflow step started as a Unix timestamp.
133+
`action-start-time` | The time that the workflow step started in a readable format (UTC, depending on runner).
134+
135+
# Considerations
136+
137+
## Common pitfalls
138+
139+
### Grant Actions permission to read and write to the repository
110140

111141
This must be changed in the repository settings by selecting "Read and
112142
write permissions" at **Settings** > **Actions** > **General** >
113143
**Workflow permissions**. Otherwise, the Action won't be able to make any
114144
changes to your deployment branch.
115145

116-
#### Set a concurrency group
146+
### Run on all appropriate pull request events
117147

118-
I highly recommend [setting a concurrency
119-
group](https://docs.github.com/en/actions/using-jobs/using-concurrency)
120-
scoped to each PR using `github.ref` as above, which should prevent the
121-
preview and comment from desynchronising if you are e.g. committing very
122-
frequently.
148+
Be sure to [pick the right event
149+
types](https://docs.github.com/en/actions/using-workflows/events-that-trigger-workflows#pull_request)
150+
for the `pull_request` event. It only comes with `opened`, `reopened`, and
151+
`synchronize` by default &mdash; but this Action assumes by default that
152+
the preview should be removed during the `closed` event, which it only sees
153+
if you explicitly add it to the workflow.
123154

124-
#### Ensure your main deployment is compatible
155+
### Ensure your main deployment is compatible
125156

126157
If you are using GitHub Actions to deploy your GitHub Pages sites
127158
(typically on push to the main branch), there are some actions you should
@@ -161,11 +192,11 @@ vice-versa.
161192
all files in the deployment location. This will destroy any ongoing
162193
preview deployments. Instead, consider adjusting your deployment
163194
workflow to rebase or merge your main deployment onto the deployment
164-
branch such that it respects other ongoing deployments.
195+
branch to respect other ongoing deployments.
165196

166197
For example, if you are using
167198
[JamesIves/github-pages-deploy-action](https://github.com/JamesIves/github-pages-deploy-action)
168-
to deploy your build, be aware that at the time of writing (v4.3.0) it
199+
to deploy your build, be aware that at the time of writing (v4.7.2) it
169200
force-pushes new deployments by default. You can disable this by setting
170201
its `force` parameter to `false`, which will prompt it to rebase new
171202
deployments instead of force-pushing them:
@@ -183,92 +214,21 @@ vice-versa.
183214

184215
This feature was introduced in v4.3.0 of the above Action.
185216

186-
####
217+
## Best practices
187218

188-
## Configuration
219+
### Run only when files are changed
189220

190-
The following configuration settings are provided, which can be passed to
191-
the `with` parameter.
192-
193-
- `source-dir`: Directory containing files to deploy.
194-
195-
E.g. if your project builds to `./dist/` you would put `./dist/` (or just
196-
`dist`) here. For the root directory of your project, put `.` here.
197-
198-
Equivalent to
199-
[JamesIves/github-pages-deploy-action](https://github.com/JamesIves/github-pages-deploy-action)
200-
'folder' setting.
201-
202-
Will be ignored when removing a preview.
203-
204-
Default: `.`
205-
206-
- `preview-branch`: Branch on which the previews will be deployed. This
207-
should be the same branch that your GitHub Pages site is deployed from.
208-
209-
Default: `gh-pages`
210-
211-
- `umbrella-dir`: Name of the directory containing all previews. All
212-
previews will be created inside this directory.
213-
214-
The umbrella directory is used to namespace previews from your main
215-
branch's deployment on GitHub Pages.
216-
217-
Set to `.` to place preview directories into the root directory, but be
218-
aware that this may cause your main branch's deployment to interfere with
219-
your preview deployments (and vice-versa!)
220-
221-
Default: `pr-preview`
222-
223-
- `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.
224-
225-
Default: ` ` (repository root)
226-
227-
- `custom-url`: Base URL to use when providing a link to the preview site.
228-
229-
Default: Will attempt to calculate the repository's GitHub Pages URL
230-
(e.g. "rossjrw.github.io").
231-
232-
- `deploy-repository`: The repository to deploy the preview to.
233-
234-
If this value is changed from the default, the `token` parameter must also
235-
be set (see below).
236-
237-
Default: The current repository that the pull request was made in.
238-
239-
- `token`: The token to use for the preview deployment. The default value is
240-
fine for deployments to the current repository, but if you want to deploy
241-
the preview to a different repository (see `deploy-repository` above), you
242-
will need to create a [Personal Access
243-
Token](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token)
244-
with permission to access it, and [store it as a
245-
secret](https://docs.github.com/en/actions/security-guides/using-secrets-in-github-actions)
246-
in your repository. E.g. you might name that secret 'PREVIEW_TOKEN' and
247-
use it with `token: ${{ secrets.PREVIEW_TOKEN }}`.
248-
249-
Default: `${{ github.token }}`, which gives the action permission to
250-
deploy to the current repository.
251-
252-
- **(Advanced)** `action`: Determines what this action will do when it is
253-
executed. Supported values: `deploy`, `remove`, `none`, `auto`.
254-
255-
- `deploy`: will attempt to deploy the preview and overwrite any
256-
existing preview in that location.
257-
- `remove`: will attempt to remove the preview in that location.
258-
- `auto`: the action will try to determine whether to deploy or remove
259-
the preview based on [the emitted
260-
event](https://docs.github.com/en/developers/webhooks-and-events/webhooks/webhook-events-and-payloads#pull_request).
261-
It will deploy the preview on `pull_request.types.opened`, `.reopened`
262-
and `.synchronize` events; and remove it on `pull_request.types.closed`
263-
events. It will not do anything for all other events, even if you
264-
explicitly specify that the workflow should run on them.
265-
- `none` and all other values: the action will not do anything.
266-
267-
Default value: `auto`
221+
Consider limiting this workflow to run [only when relevant files are
222+
edited](https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#onpushpull_requestpull_request_targetpathspaths-ignore)
223+
to avoid deploying previews unnecessarily.
268224

269-
## Outputs
225+
### Set a concurrency group
270226

271-
- `deployment-url`: the URL at which the preview has been deployed.
227+
I highly recommend [setting a concurrency
228+
group](https://docs.github.com/en/actions/using-jobs/using-concurrency)
229+
scoped to each PR using `github.ref` as above, which should prevent the
230+
preview and comment from desynchronising if you are e.g. committing very
231+
frequently.
272232

273233
## Examples
274234

@@ -394,13 +354,11 @@ jobs:
394354
action: deploy
395355
```
396356

397-
## Acknowledgements
357+
# Acknowledgements
398358

399359
Big thanks to the following:
400360

401-
- [shlinkio/deploy-preview-action](https://github.com/shlinkio/deploy-preview-action)
402-
(MIT), prior art that informed the direction of this Action
403-
- [JamesIves/github-pages-deploy-action](https://github.com/JamesIves/github-pages-deploy-action)
404-
(MIT), used by this Action to deploy previews
405-
- [marocchino/sticky-pull-request-comment](https://github.com/marocchino/sticky-pull-request-comment)
406-
(MIT), used by this Action to leave a sticky comment on pull requests
361+
- [shlinkio/deploy-preview-action](https://github.com/shlinkio/deploy-preview-action) (MIT), prior art that informed the direction of this Action
362+
- [JamesIves/github-pages-deploy-action](https://github.com/JamesIves/github-pages-deploy-action) (MIT), used by this Action to deploy previews
363+
- [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
364+
- [Everyone who has contributed](https://github.com/rossjrw/pr-preview-action/graphs/contributors) to this Action

0 commit comments

Comments
 (0)