Skip to main content
← All 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.

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.

More

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
OptionWho can open a preview by defaultAccess controlWhat it needsWhen 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 shareA job that can run the app; no account or repository secretWhen the job ends: the review window, a new push, a closed pull request, or the 120-minute job timeout
Vercel preview deploymentDeployment protection is enabled by default for new projectsVercel Authentication on Hobby, for one external user per account; password protection is not on HobbyA Vercel project connected to the repositoryAs long as your deployment retention policy keeps it
Netlify Deploy PreviewsPrivate for new projects on teams created on or after July 28, 2026; public on older teamsPrivate: Netlify login for your team and people you invite (Credit-based plans); password protection on ProA Netlify project connected to the repositoryNetlify deletes deploys after 30 days by default, 90 on paid plans
Cloudflare Pages preview deploymentsPublic: “available publicly” by default“Enable access policy” makes visitors authenticate; it covers preview URLs, not *.pages.dev or a custom domainA Pages project connected to GitHubNot documented
Render Preview EnvironmentsNot documentedNot documentedA Pro workspace plan or higher and a Blueprint; billed like other Render servicesWhen the pull request is merged or closed, or after an expiry you set
Heroku Review AppsNot documentedNot documentedHeroku Pipelines and GitHub integration; dynos and add-ons billed as for normal appsWith the pull request, or after 1, 2, 5, 14 or 30 days of inactivity
Railway PR environmentsNot documentedNot documentedPR environments turned on in Project Settings; domains only when the base environment has Railway-provided domainsWhen the pull request is merged or closed

Sources: GitHub Actions limits, Vercel: deployment protection on by default, Vercel Authentication, Netlify: project visibility, Netlify: managing deploys, Cloudflare Pages: preview deployments, Render: preview environments, Heroku: review apps, Railway: environments.

Troubleshooting

Troubleshooting
If you seeDo this
The job fails with “publish failed” and a log that says the local app cannot be reachedThe 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.
Show 8 more fixes
More troubleshooting
If you seeDo 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 doneA 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 connectionsStart 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: lineYour 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 →
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.

Publish your app now

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

Install the CLI →

Book a pilot

Tell us what to hide. We’ll scope a pilot.

Enterprise starts with a paid pilot on one application, typically 60 to 90 days, credited in full toward year one if you convert within 60 days. After that, an annual package sized to what you protect, not per seat.