Setting Up Netlify Deploy Previews for Pull‑Request Review URLs

Desired outcome

Every pull request opened against the repository’s base branch triggers a Netlify Deploy Preview that provides a unique, shareable URL for stakeholders to test changes before they are merged.

Prerequisites

• The repository is already linked to a Netlify site (you have admin access to the site).
• Netlify CLI version ≥ 2.0 is installed locally and you are logged in (netlify login).
• The site has a working build command and publish directory defined either in netlify.toml or via the dashboard.
• You have push access to the repository and permission to create pull requests.

Procedure

1. Enable branch deploys and deploy previews
   1. In the Netlify dashboard, open your site → Site settings → Build & deploy → Continuous Deployment.
   2. Turn on Branch deploys and Deploy previews.
   3. Save changes.
2. Add a deploy‑preview context to netlify.toml

   # netlify.toml
   [build]
     command = "npm run build"
     publish = "dist"
   
   [context.deploy-preview]
     command = "npm run build"
   

   Place this file at the repository root; if you already have a netlify.toml, add the [context.deploy-preview] section.

3. Push a feature branch and open a pull request

   # Local machine
    git checkout -b feature/preview-demo
    # make changes, commit
    git push -u origin feature/preview-demo
    # Open a PR against your base branch (e.g., main) via GitHub/GitLab/Bitbucket UI
   

4. Verify Netlify creates the preview
   • Netlify should automatically start a deploy for the branch.
   • When the build finishes, Netlify posts a comment on the PR containing the preview URL.

Expected checks

• In the Netlify dashboard, go to Deploys → Deploy previews and confirm a new deploy appears linked to the PR branch.
• Open the deploy log and verify the build completed without errors.
• Run curl -I <preview‑url> (replace <preview‑url> with the URL from the PR comment) and look for HTTP/2 200.
• Check the PR conversation for a comment from Netlify that includes the preview URL; clicking it should load the live preview in a browser.
• Optionally, retrieve the URL via CLI: netlify open:preview --site <SITE-ID> after pushing the branch.

Recovery options (including rollback)

• Inspect failures: If the preview deploy fails, open the deploy log in the dashboard to identify build errors or missing environment variables.
• Adjust configuration: Modify the build command, add required netlify.toml variables, or adjust the [context.deploy-preview] section to match the default build context.
• Revert to known‑good commit: Push a fix or revert the offending commit; Netlify will trigger a new preview deploy.
• Temporarily disable previews: In site settings → Build & deploy → Continuous Deployment, turn off Deploy previews while you resolve the issue. This is a rollback‑like action because it changes the site’s deploy behavior.
• Monitor usage: Preview builds consume build minutes; check your plan’s usage under Team overview → Usage to avoid exceeding free‑tier limits.

Limitations and practical verification

• Preview URLs are publicly accessible by default; avoid storing secrets in the build unless you scope environment variables to production contexts ([context.production]).
• Heavy build steps or large repositories can quickly exhaust build minutes on the free tier; consider upgrading or caching dependencies.
• Changes made to [context.deploy-preview] that diverge from the default build context may cause inconsistencies between preview and production deploys; keep them aligned unless you have a specific reason to differ.