# Give every pull request a private preview from GitHub Actions

> Private pull request previews from GitHub Actions, no Vercel, Netlify or Render needed: qURL serves each build from the job to reviewers you allow. No secrets.

Source: https://layerv.ai/guides/private-pull-request-previews-on-github-actions/

---

[← All guides](https://layerv.ai/guides/) 

# Give every pull request a private preview from GitHub Actions

## Why qURL here

Run a private preview environment for each pull request directly from its GitHub Actions job. qURL™ limits access to the reviewer device keys you allow, with no shared credential or deployed copy.

Copies a prompt for any agent that runs commands. 

## What you need

- A GitHub repository whose app builds and starts on a Linux runner
- Reviewers with the qURL CLI and jq installed on their own computers
- Permission to add a repository variable and a workflow file

Content updated November 4, 2026.

## Steps

For a private preview environment per pull request, run the app in the pull request’s GitHub Actions job, publish it with qURL in the foreground, and allow each reviewer’s device key with `qurl grants --add`. The workflow posts the CRID on the pull request; it is safe there, because a private CRID opens nothing for anyone else. Reviewers run `qurl get` <CRID>. No secret is stored, and the preview lasts while the job runs.

1. ### Collect each reviewer’s device key  
Each reviewer runs this once on the computer they review from. The first run creates that computer’s qURL identity, with no account, and prints its public key. A public key is not a secret: it lets that one device open what you allow it to, and nothing else.  
```  
qurl whoami -o json | jq -r .device_public_key_b64
```
2. ### Store the keys as a repository variable  
Put the keys in one variable, separated by spaces. Use a variable, not a secret: the keys are public, and a variable keeps them readable when you add or remove a reviewer. Removing a key from the variable takes that device off the next preview.  
```  
gh variable set QURL_REVIEWER_KEYS --body "<key-1> <key-2>"
```
3. ### Add the workflow  
On each push to a pull request from this repository, the job builds and starts the app on 127.0.0.1, installs a pinned qURL CLI, and publishes the app in the foreground, so the share belongs to the job and ends with it. It allows each reviewer key, confirms the resource is private, names it after the pull request, and comments the command to open it. A new push cancels the previous run, so the preview always shows the latest commit. Closing or merging the pull request also cancels its preview. Each run holds a runner for about 90 minutes plus the build; shorten the review window to reduce billed minutes. Pull requests from forks are skipped: their token is read-only and their code would run in your job.  
```  
# .github/workflows/pr-preview.yml
name: PR preview
on:
  pull_request:
    types: [opened, synchronize, reopened, closed]
concurrency:
  group: pr-preview-${{ github.event.pull_request.number }}
  cancel-in-progress: true
permissions:
  contents: read
  pull-requests: write
jobs:
  preview:
    # A fork's pull request gets a read-only token, and its code is untrusted.
    if: github.event.action != 'closed' && github.event.pull_request.head.repo.full_name == github.repository
    runs-on: ubuntu-latest
    timeout-minutes: 120
    steps:
      - uses: actions/checkout@v4
      - name: Start the app on 127.0.0.1:3000
        run: |
          # Replace with your app's own build and start commands.
          npm ci && npm run build
          nohup npm start > app.log 2>&1 &
          for _ in $(seq 1 60); do
            curl -fsS -o /dev/null http://127.0.0.1:3000 && break
            sleep 1
          done
          curl -fsS -o /dev/null http://127.0.0.1:3000 || { cat app.log; exit 1; }
      - name: Install the qURL CLI
        run: |
          (umask 022 && mkdir -p "$HOME/.local/bin" "$HOME/.local/state") &&
            chmod go-w "$HOME/.local" "$HOME/.local/bin" "$HOME/.local/state" &&
            installer=$(mktemp) &&
            curl -fsSL --retry 3 --proto '=https' -o "$installer" \
              https://raw.githubusercontent.com/layervai/qurl-integrations/main/scripts/install.sh &&
            INSTALL_DIR="$HOME/.local/bin" VERSION=3.6.1 sh "$installer" &&
            rm -f "$installer"
          export PATH="$HOME/.local/bin:$PATH"
          qurl --version
          echo "$HOME/.local/bin" >> "$GITHUB_PATH"
      - name: Publish for the reviewers' devices
        env:
          GH_TOKEN: ${{ github.token }}
          PR_NUMBER: ${{ github.event.pull_request.number }}
          HEAD_SHA: ${{ github.event.pull_request.head.sha }}
          QURL_REVIEWER_KEYS: ${{ vars.QURL_REVIEWER_KEYS }}
        run: |
          [ -n "$QURL_REVIEWER_KEYS" ] || { echo "QURL_REVIEWER_KEYS is empty"; exit 1; }
          run=$(mktemp -d)
          nohup qurl publish http://127.0.0.1:3000 --foreground --quiet \
            > "$run/crid" 2> "$run/publish.log" < /dev/null &
          pub=$!
          for _ in $(seq 1 90); do
            [ "$(wc -c < "$run/crid")" -ge 60 ] && break
            kill -0 "$pub" 2>/dev/null || break
            sleep 1
          done
          CRID=$(head -n 1 "$run/crid")
          [ -n "$CRID" ] || { echo "publish failed:"; cat "$run/publish.log"; kill "$pub" 2>/dev/null; false; }
          echo "CRID=$CRID" >> "$GITHUB_ENV"
          for key in $QURL_REVIEWER_KEYS; do
            qurl grants "$CRID" --add "$key" -o json > /dev/null
          done
          qurl grants "$CRID" -o json | jq -e '.private == true' > /dev/null
          qurl preview set "$CRID" --name "PR $PR_NUMBER preview" -o json > /dev/null
          gh pr comment "$PR_NUMBER" --body "Private preview of ${HEAD_SHA::7}, up for 90 minutes. If your device key is in QURL_REVIEWER_KEYS, open it with: qurl get $CRID"
      - name: Hold the review window
        run: sleep 5400   # keep it under timeout-minutes
      - name: Delete the preview resource
        if: always()
        run: |
          if [ -n "$CRID" ]; then qurl delete "$CRID" --yes; fi
```
4. ### Open the preview  
A reviewer whose key is in the variable copies the command from the pull request comment. On a terminal, `qurl get` mints a fresh link for that device, checks it against the CRID, and opens it in their default browser. Anyone else who runs it gets “not found”.  
```  
qurl get <CRID>
```
5. ### Bring in a reviewer without the CLI  
A reviewer whose device is allowed can make a one-time link for someone else, such as a designer or a client, and send it to them directly. The link opens once and is a secret, so it never goes in the pull request.  
```  
qurl share <CRID> --ttl 1h
```

## What the recipient sees

A reviewer runs qurl get with the CRID from the comment, and the build of that pull request opens in their browser, served from the GitHub runner.

When the review window ends, a new push cancels the run, or the pull request closes, the preview stops answering.

## Pull request preview options compared

Who can open each preview by default, and what keeps others out. Vendor rows quote each vendor’s docs, checked on 2026-11-04; “not documented” means the page we cite does not say.

__Pull request preview options compared__
| Option                                      | Who can open a preview by default                                                          | Access control                                                                                                  | What it needs                                                                                                      | When it ends                                                                                           |
| ------------------------------------------- | ------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------ |
| qURL from a GitHub Actions job (this guide) | Only the device keys you allow; anyone else gets “not found”                               | Device keys with qurl grants --add; one-time links from qurl share                                              | A job that can run the app; no account or repository secret                                                        | When the job ends: the review window, a new push, a closed pull request, or the 120-minute job timeout |
| Vercel preview deployment                   | Deployment protection is enabled by default for new projects                               | Vercel Authentication on Hobby, for one external user per account; password protection is not on Hobby          | A Vercel project connected to the repository                                                                       | As long as your deployment retention policy keeps it                                                   |
| Netlify Deploy Previews                     | Private for new projects on teams created on or after July 28, 2026; public on older teams | Private: Netlify login for your team and people you invite (Credit-based plans); password protection on Pro     | A Netlify project connected to the repository                                                                      | Netlify deletes deploys after 30 days by default, 90 on paid plans                                     |
| Cloudflare Pages preview deployments        | Public: “available publicly” by default                                                    | “Enable access policy” makes visitors authenticate; it covers preview URLs, not \*.pages.dev or a custom domain | A Pages project connected to GitHub                                                                                | Not documented                                                                                         |
| Render Preview Environments                 | Not documented                                                                             | Not documented                                                                                                  | A Pro workspace plan or higher and a Blueprint; billed like other Render services                                  | When the pull request is merged or closed, or after an expiry you set                                  |
| Heroku Review Apps                          | Not documented                                                                             | Not documented                                                                                                  | Heroku Pipelines and GitHub integration; dynos and add-ons billed as for normal apps                               | With the pull request, or after 1, 2, 5, 14 or 30 days of inactivity                                   |
| Railway PR environments                     | Not documented                                                                             | Not documented                                                                                                  | PR environments turned on in Project Settings; domains only when the base environment has Railway-provided domains | When the pull request is merged or closed                                                              |

Sources: [GitHub Actions limits](https://docs.github.com/en/actions/reference/limits) , [Vercel: deployment protection on by default](https://vercel.com/changelog/deployment-protection-is-now-enabled-by-default-for-new-projects) , [Vercel Authentication](https://vercel.com/docs/deployment-protection/methods-to-protect-deployments/vercel-authentication) , [Netlify: project visibility](https://docs.netlify.com/manage/security/secure-access-to-sites/project-visibility/) , [Netlify: managing deploys](https://docs.netlify.com/deploy/manage-deploys/manage-deploys-overview/) , [Cloudflare Pages: preview deployments](https://developers.cloudflare.com/pages/configuration/preview-deployments/) , [Render: preview environments](https://render.com/docs/preview-environments) , [Heroku: review apps](https://devcenter.heroku.com/articles/github-integration-review-apps) , [Railway: environments](https://docs.railway.com/guides/environments).

## Troubleshooting

__Troubleshooting__
| If you see                                                                              | Do this                                                                                                                                                                                 |
| --------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| The job fails with “publish failed” and a log that says the local app cannot be reached | The app was not listening on 127.0.0.1:3000 when publish started. Check app.log, and make sure the start command binds 127.0.0.1 on the port you publish.                               |
| A reviewer’s qurl get answers “not found”                                               | That device’s key was not in QURL\_REVIEWER\_KEYS when the job ran, or the run already ended. Have them run qurl whoami -o json again and compare the key, then push or re-run the job. |

__More troubleshooting__
| If you see                                                                                                             | Do this                                                                                                                                                                                                                                                                                                                                                                                                                               |
| ---------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| gh pr comment fails with “Resource not accessible by integration”                                                      | The job’s token cannot write to pull requests. Keep pull-requests: write in the workflow’s permissions, and check that the repository’s Actions settings do not force a read-only token.                                                                                                                                                                                                                                              |
| The preview vanished before the review was done                                                                        | A new push cancelled the run, or the job reached timeout-minutes. Re-run the job; each run makes a new CRID and a new comment.                                                                                                                                                                                                                                                                                                        |
| qurl publish says the local app is not accepting TCP connections                                                       | Start the app first and check that curl works on the same address. qurl publish connects to localhost as 127.0.0.1, so if your app listens only on IPv6 (on macOS or Linux, lsof -iTCP -sTCP:LISTEN -nP shows \[::1\]), publish 'http://\[::1\]:PORT' instead, or start the dev server with --host 127.0.0.1 and publish that address. Neither requires listening on your LAN. Keep the quotes: zsh treats the brackets as a pattern. |
| The recipient sees “Access link invalid”                                                                               | The link was already used or has expired. Run qurl share again and send the new link.                                                                                                                                                                                                                                                                                                                                                 |
| The recipient sees “Resource not found”                                                                                | The resource was deleted after the link was made. Publish the app again, then run qurl share and send the new link.                                                                                                                                                                                                                                                                                                                   |
| publish rejects http://127.0.0.1 with “only HTTPS URLs are allowed”, asks you to log in, or prints no Access: line     | Your qURL CLI is out of date. On macOS run brew update, then brew upgrade qurl; elsewhere install the latest release. After updating, qurl --version prints 3.4.1 or later, and every publish is private by default.                                                                                                                                                                                                                  |
| publish says this Linux session “can’t reach a systemd user manager”                                                   | You are in a container or sandbox without a user service manager. Run qurl publish with --foreground; sharing lasts as long as that process runs. [Container and CI setup →](https://layerv.ai/guides/share-from-a-container-or-ci/)                                                                                                                                                                                                  |
| publish says “Quota Exceeded” with “protected resource limit reached”, or “Your qURL account has reached a plan limit” | You can see this without an account: a device with no account can keep up to 3 active resources, with links that last up to 24 hours. Run qurl list --status active, then qurl delete <CRID> for any you no longer need (it asks you to confirm; --yes skips that). qurl stop keeps the resource, so it does not free a slot.                                                                                                         |

## Frequently Asked Questions

Is it safe to post the CRID on a public repository? 

Yes, for a private resource, which is what the workflow checks with jq before it comments. A private CRID opens only for the publishing runner and the device keys you allowed; anyone else gets “not found”. Never post a link from qurl share there: a link is a secret.

Why not store one key in CI and reuse it? 

There is nothing to store. Each run’s first publish creates a fresh device identity on the runner, and that identity is thrown away with the runner after the job. Don’t copy the qurl state directory into a cache or artifact: it holds the device credential.

What happens to a run that is cancelled? 

The runner stops the publisher, so the preview stops answering. The final cleanup step also runs after cancellation and deletes the registered resource. A forced runner shutdown can prevent cleanup; each new run uses a fresh device identity and creates a new CRID.

Can it run on pull requests from forks? 

Not as written. GitHub gives a fork’s pull\_request run a read-only token, so the comment fails, and the run builds code you have not reviewed. Review the change first, then push it to a branch in your repository.

Are Vercel, Netlify and Cloudflare Pages previews public? 

It depends on the host. Vercel enables deployment protection by default for new projects. Netlify makes new projects private on teams created on or after July 28, 2026, and public on older teams. Cloudflare Pages preview deployments are public by default until you enable an access policy. All three host a build of your app; qURL serves the build running in your job, with nothing deployed.

Can I run ngrok or a Cloudflare tunnel in GitHub Actions instead? 

Yes, but the preview is public. ngrok needs an account, so its authtoken goes into a repository secret, and the URL is open to anyone unless a Traffic Policy adds a login. A Cloudflare Quick Tunnel needs no account, but its trycloudflare.com URL is public unless you set --allowed-mail. Posting either URL on a pull request shows the build to everyone who can read it.

What about tmate or upterm in GitHub Actions? 

Those give you a shell on the runner to debug a job, not a web preview for reviewers. action-upterm can restrict SSH to the user who triggered the workflow. action-tmate’s README says the public tmate servers were shut down in July 2025, so it no longer works with its default settings.

Can a coding agent open the pull request and review the preview? 

Yes. A pull request from a branch in your repository runs the workflow whoever opened it, Claude Code, Codex or a person. To let the agent look too, add the key of the machine it runs on to QURL\_REVIEWER\_KEYS; it can then run qurl share <CRID> --ttl 1h and open that link in its browser tool.

Who else can reach my app while the link is open? 

Opening the link starts a session for that browser, which lasts 1 hour by default. After a browser opens it, another browser on the same public IP cannot use its access. A script or agent that opens the link without a browser is admitted by its network address instead, which other devices on that public IP share until the session ends. A link admits whoever opens it: the API’s IP and country rules do not apply to the signed links qurl share issues. Keep your app’s own sign-in for anything sensitive.

## Related Resources

[Guide: Share an app from a container or CI →](https://layerv.ai/guides/share-from-a-container-or-ci/) [Guide: Share an app from a GitHub Codespace privately →](https://layerv.ai/guides/share-a-codespace-privately/) [Guide: Share an app from a remote dev server over SSH →](https://layerv.ai/guides/share-from-a-remote-dev-server/) [Guide: Share a preview from each git worktree →](https://layerv.ai/guides/share-previews-from-git-worktrees/) [Deploy previews vs sharing localhost →](https://layerv.ai/compare/deploy-preview-vs-share-localhost/) [qURL vs ngrok →](https://layerv.ai/compare/qurl-vs-ngrok/) [qURL vs Cloudflare Quick Tunnels →](https://layerv.ai/compare/qurl-vs-cloudflare-quick-tunnels/) [ngrok alternatives with authentication →](https://layerv.ai/compare/ngrok-alternatives-with-auth/) [GitHub docs: Events that trigger workflows ↗](https://docs.github.com/en/actions/reference/workflows-and-actions/events-that-trigger-workflows) [qURL CLI →](https://layerv.ai/cli/)

## Publish your app now

Install the CLI, then run one command. No sign-up, no API key.

[Install the CLI →](https://layerv.ai/cli/)



---

*This markdown version is auto-generated from [https://layerv.ai/guides/private-pull-request-previews-on-github-actions/](https://layerv.ai/guides/private-pull-request-previews-on-github-actions/) for AI agents. Curated agent resources: [llms.txt](https://layerv.ai/llms.txt). For the full interactive experience, visit the HTML version.*

