service/static-shim.md

@@ -109,6 +109,11 @@ used. To opt-out of Review Apps, define `SKIP_REVIEW_APPS: 1` in the
 The active environments linked to Review Apps can be listed by
 navigating to the project page -> Deployments -> Environments.
 
+An HTTP authentication is required to access these environments: the
+username is `tor-www` and the password is blank. These credentials
+should be automatically present in the URLs used to access Review Apps
+from the GitLab interface.
+
 Please note that Review Apps do not currently work for Merge Requests
 created from personal forks. This is because personal forks do not have
 access to the SSH private key required to deploy to the static mirror
@@ -121,26 +126,26 @@ auto-stopped (deleted) after 1 week without being updated.
 
 ## Working with a staging environment
 
-Some projects such as `blog.torproject.org` have a specific staging area
-that is separate from GitLab Pages and `review.torproject.net`.
+Our web projects have a specific staging area that is separate from
+GitLab Pages and `review.torproject.net`. Those sites are deployed as
+subdomains of `*.staging.torproject.net` on the static mirror system.
+For example, the staging URL for `blog.torproject.org` is
+`blog.staging.torproject.net`.
 
 Staging environments can be useful in various scenarios, such as when
 the build job for the production environment is different than the one
 for Review Apps, so a staging URL is useful to be able to preview a full
 build before being deployed to production.
 
-To enable a staging environment, first a new domain name must be
-created and pointed to `static.torproject.org`. An example is
-`blog-staging.torproject.org` for the blog. This step must be done by
-TPA, so please [open a ticket](https://gitlab.torproject.org/tpo/tpa/team/-/issues/new).
-
-Then, a new SSH key must be added to Puppet, using the same procedure as
-for the production environment (see [above](#deploying-a-static-site-from-gitlab-ci)).
-Only in this case, when adding the private key to CI/CD variables, use
-`staging` as Environment scope instead of `production`.
+To enable a staging environment, first a DNS entry must be created
+under `*.staging.torproject.net` and pointed to
+`static.torproject.org`. Then some configuration changes are needed in
+Puppet so the necessary symlinks and vhosts are created on the static
+web mirrors. These steps must be done by TPA, so please
+[open a ticket](https://gitlab.torproject.org/tpo/tpa/team/-/issues/new).
 
 Lastly, a `STAGING_URL` variable must be added to `.gitlab-ci.yml` with
-the staging domain name (eg. `blog-staging.torproject.org`) as its
+the staging domain name (eg. `blog.staging.torproject.org`) as its
 value.
 
 Once this is in place, commits added the the default (`main`) branch
@@ -148,6 +153,11 @@ will automatically trigger a deployment to the staging URL and a manual
 job for deployment to production. **This manual job must then be
 triggered by hand after the staging deployment is QA-cleared.**
 
+An HTTP authentication is required to access staging environments: the
+username is `tor-www` and the password is blank. These credentials
+should be automatically present in the `Open` and `View deployment`
+links in the GitLab interface.
+
 # How-to
 
 ## Adding a new static site shim in Puppet