creating_review_app.md

November 7, 2025 ยท View on GitHub

Creating a Force Review App

Quick Start

To create a review app on Artsy.net:

Further commits to the branch will update and deploy changes to the review app.

Detailed Info

For those that are curious about what's going on behind the scenes, read on!

If you want to create a deploy for a WIP feature or for QA, Hokusai supports Review Apps.

You can create a review app via CircleCI which runs the build_review_app.sh script. Or, you can run that script locally, which will be slower because it involves building the docker image locally and pushing it up to AWS ECR.

The rest of the doc assumes you are working with a review app called awesome-feature.

Building on Circle

This is the easiest and fastest way. Push up a branch named review-app-awesome-feature

CircleCI will match the review-app- prefix and either:

  1. Create a review app using build_review_app.sh if the review app doesn't exist yet (i.e. first successful push of the branch), or
  2. Update an existing review app using update_review_app.sh
  3. Once CI is complete follow this step to setup DNS.

Building on Local

First, make sure jq is installed:

brew install jq

Then launch the script with:

./scripts/build_review_app.sh awesome-feature

The script will save a K8s spec in hokusai/awesome-feature.yml

Accessing the review app.

To access the review app, you must create a DNS name for it. The name must match the name of the review app, and it must end in artsy.net. So it must be awesome-feature.artsy.net. This is required for full OAuth flow to complete. On Cloudflare, please do:

  1. Login to Cloudflare, and navigate to artsy.net > DNS
  2. Click + Add Record
  3. Change Type dropdown to CNAME
  4. Under Name enter awesome-feature
  5. Under Target say nginx-staging-2025.artsy.net
  6. Under Proxy status toggle to Proxied
  7. Under Record Attributes > Comment add the PR that created the review app, e.g. https://github.com/artsy/force/pull/123
  8. Under Record Attributes > Tags add the prefix of your team, e.g. FX
  9. Hit Save
  10. DNS will propagate and after a few minutes the review app will be available via awesome-feature.artsy.net

Setting ENV variables on the review app

To set an ENV variable, run:

hokusai review_app env set <my-review-app-name> SOME_ENV_VAR=true
hokusai review_app refresh <my-review-app-name>

Updating the review app

If the review app was created via Circle as mentioned above, simply push up your changes on the review-app-awesome-feature branch.

If the app was built locally, do:

hokusai registry push --overwrite --skip-latest --force --tag awesome-feature

and redeploy the app:

hokusai review_app deploy awesome-feature awesome-feature

Deleting a Review App

You should delete review apps as soon as QA is complete.

Delete the app by:

yarn delete-review-app awesome-feature

Delete its DNS entry by:

  1. Login to Cloudflare, and navigate to artsy.net > DNS
  2. In the search box, type awesome-feature
  3. Locate the correct record in search results, hit Edit at end of line
  4. Hit the Delete button on lower left

Conclusion

For more info on Review App maintenence, see Hokusai docs.

Read over the build_review_app.sh script for more info on how this is all done.