Skip to main content
Skip table of contents

Using review instances to preview changes

If you need to do additional testing and verification outside of your local development environment, you can deploy changes from a branch or pull request. Review instances allow you to view changes to services or applications on the backend and frontend.

Reviewing visual or content changes to

Review instances require access to the SOCKS proxy (docs: , which means they cannot be reviewed by external stakeholders.

Review instances are created as part of a pull request for the vets-api, vets-website, or content-build GitHub repositories, but they can also be created manually by running a Jenkins job.

Screenshot of what the Review Instance link looks like.

Go to your Review Instance by clicking “View deployment” in your PR

Automatic creation

The Jenkins files in vets-website and vets-api define a stage that triggers a review instance deployment. Opening a PR will trigger the continuous integration (CI) process, which will generate a GitHub Deployment for the PR. A message on the PR will provide a link to the review instance.

Make sure your browser is configured to access the vetsgov-internal domain via the SOCKS proxy. See for detailed instructions.

Manual creation

If you made changes to branches in both vets-website and vets-api, and you want to test the changes together, you can manually trigger a build.

  1. Visit  and log in.

  2. Select "Build with Parameters."

  3. Specify the branch names for api_branch and web_branch. These branches will be deployed together with the review instance.

  4. When the process is completed, the URL for the review instance will be provided at the end of the output logs.

Access and usage

Review instances run on an independent virtual machine on which both vets-api and vets-website are installed. A nginx proxy in the front end directs requests. The web interface (vets-website) and API (vets-api) are available over HTTP behind the SOCKS proxy.


The review instances are accessible via SSH and you can modify code and see the changes. See  to set up SSH access.

Code is re-deployed on each commit which could result in lost changes local to the review instance. 

To connect, retrieve the hostname of the instance:

  1. Click the Deployed button in the GitHub deployment panel to open the Jenkins job.

  2. Click Console output to view the provisioning task.

  3. Search for Review instance available at on the page, which will give you the hostname string for SSH access.

Once you have the hostname, login with: ssh dsva@<hostname>

Common tasks

Both vets-website and vets-api processes are managed via Docker Compose. The code is stored in the dsva user's home directory. You might need to perform the following common tasks in a SSH session on the review instances.

  • To view build and access logs for the development web server, enter the following command (enter Ctrl-C to exit):

    cd ~/vets-website; docker-compose -f logs -f

    This will include both build logs and access logs to the development web server running.

  • To rebuild vets-website after modifying the code, enter the following command:

    cd ~/vets-website; docker-compose -f restart vets-website

You will not be able to view the instance while the website is building. The website will return 502 errors until the build process finishes and the server restarts. To check progress or troubleshoot if you suspect the build failed, use the command above to view logs.

  • To troubleshoot, start a shell session in the build environment using the following command:

    cd ~/vets-website; docker-compose -f exec vets-website bash

  • To force a restart of Puma or Sidekiq, enter the following command:

    cd ~/vets-api; docker-compose -f restart vets-api

    On review instances, Puma is running with RAILS_ENV=development, which enables live-reloading of some files, but not all. This means that you will not be able to see some code changes until you force a restart. The vets-api service in the compose file includes both Puma and Sidekiq.

  • To view stdout of Puma or Sidekiq processes, enter the following command (enter Ctrl-C to exit):

    cd ~/vets-api; docker-compose -f logs -f vets-api

    • Do not add -f if you only want to view the files one time.

    • In development mode, vets-api does not log to stdout. It logs to log/development.log like it would on a local installation.

  • To rebuild the container and start over, enter the following command:

    cd ~/vets-api; docker-compose -f down -v; docker-compose -f up -d

    Running this command results in downtime for the instance.

  • To open a Rails console, enter the following command:

    cd ~/vets-api; docker-compose -f exec vets-api bundle exec rails c

  • To get a bash shell in one of the containers, enter the following command:

    cd ~/vets-api; docker-compose -f exec vets-api bash


The review instance is deleted when the non-main branch that a review instance is related to is deleted or when the instance is older than 7 days.

User authentication

The review instance requires a special nginx configuration that intercepts the callback to the server, and forwards the authentication information to the appropriate review instance. The information is mapped by the RelayState parameter, which is provided to the review instance vets-api config with the REVIEW_INSTANCE_SLUG environment variable).

For implementation-specific details, see the revproxy nginx configuration.

Implementation details of Review Instances

Implementation details of the authentication for Review Instances

JavaScript errors detected

Please note, these errors can depend on your browser setup.

If this problem persists, please contact our support.