What does a project need before `cypress run --record` uploads to Cypress Cloud?
answer
- Two values, one public one secret
- Which project, and may you write
- Six characters in the config file
- A GUID from the CI secret store
- CYPRESS_RECORD_KEY replaces --key
basics
~10 sTwo things: a projectId in the Cypress config (or CYPRESS_PROJECT_ID) naming the Cloud project, and a record key passed as --key or exported as CYPRESS_RECORD_KEY. The projectId says where; the key authorises writing there.
solid answer
~40 s`cypress run --record` needs a **project identity** and a **write credential**. The identity is `projectId`, a six-character string Cypress writes into your Cypress configuration file when you set the project up to record; check it into source control, or supply `CYPRESS_PROJECT_ID` if you would rather not commit it. The credential is the record key, a GUID passed as `cypress run --record --key <key>` or — far more common in CI — exported once as `CYPRESS_RECORD_KEY` so the flag can be dropped. The key only grants *writing* runs, not reading them, so anyone with the `projectId` and a key can record into your project: keep it in the CI secret store and regenerate it if it leaks. In a storefront monorepo every package's job records against the same `projectId`.
code
bash · 5 lines# projectId lives in cypress.config.js; the key comes from CI secrets
export CYPRESS_RECORD_KEY="$CI_SECRET_RECORD_KEY"
# --key can now be omitted entirely
npx cypress run --record --spec 'cypress/e2e/packages/checkout/**/*'go deeper
Be ready to name both halves without hesitating: projectId identifies the Cloud project, the record key authorises writing to it, and CYPRESS_RECORD_KEY is how CI supplies the key.
Explain why they are separate — one is identity, one is a credential — and why the key is stored as an environment variable rather than typed into the command line of a CI job.
Show the operational habit: keys in the provider's secret store, rotation on exposure, and never treating a changed projectId as a fix, because run history is keyed to it.
Own the standard across repositories: who holds record keys, how they rotate, and whether a shared project or a project per package gives your teams the run history they actually read.
## Two identifiers, two different jobs A plain `cypress run` prints results to the terminal and forgets them. Adding `--record` uploads the run — its specs, tests, screenshots and video — to Cypress Cloud, and that upload needs exactly two pieces of information, because two different questions have to be answered. - **`projectId`** answers *which* Cloud project this run belongs to. It is a six-character string that Cypress writes into your Cypress configuration file the first time you set the project up to record. - **The record key** answers *whether this machine is allowed to write* to that project. It is a GUID that Cypress Cloud generates, and one project can hold several of them. Neither is a user login. The record key is a write credential and nothing more: it creates runs. Whether a human can later *read* those runs is a separate matter of project access in the Cloud. | | `projectId` | record key | |---|---|---| | answers | which project this is | may this machine record | | shape | six-character string | a GUID | | normal home | the Cypress config file | the CI secret store | | environment variable | `CYPRESS_PROJECT_ID` | `CYPRESS_RECORD_KEY` | | CLI flag | none | `--key` | | committed to git | yes, by default | never | | replaceable | no — a new one orphans run history | yes — delete it and create another | ## Where each one lives in a storefront monorepo One `projectId` identifies the whole Cypress project, so every package's job — `storefront-web`, `checkout`, `admin-portal` — records against the same id and shows up under the same project. The id is not a secret: the docs recommend checking the configuration file into source control with it. If you would rather keep it out of the repository, delete it from the config file and export `CYPRESS_PROJECT_ID` instead; Cypress reads it from the environment exactly the same way. What you must not do is hand-edit it to something else — Cypress then looks for a project that does not exist, and the run history attached to the old id is orphaned. The key is the half that must stay private, and it belongs wherever your pipeline keeps secrets. ## Two ways to hand over the key 1. **On the command line:** `npx cypress run --record --key f4466038-70c2-4688-9ed9-106bf013cd73`. Fine for a one-off recording from your own machine, poor in CI — the key ends up in the job's command line and very often in its log output. 2. **In the environment:** export `CYPRESS_RECORD_KEY` from the secret store and drop the flag entirely, leaving `npx cypress run --record`. Cypress picks the key up on its own. This is the form nearly every pipeline uses, and it is why most published CI examples show `--record` with no `--key` beside it. If you pass `--record` with neither, Cypress stops and tells you that you passed the `--record` flag but did not provide a record key, and points you at both ways of supplying one. ## What a leaked key actually costs Anyone holding both the `projectId` and a record key can record runs into your project. They cannot read your existing runs with it, but they can add new ones, which means junk history and recorded results nobody on your team produced, in a project the team trusts. Treat it as the write token it is: - Keep it in the CI provider's secret store, never in the repository and never in the Cypress configuration file next to `projectId`. - Prefer the environment-variable form so the value never appears in a command line or a log. - If it does leak, delete that key in Cypress Cloud and create a new one. Deleted keys stop working immediately, and nothing but the stored secret has to change. - Rotate keys freely; never "rotate" `projectId`, because every recorded run hangs off it. ## Why recording is the foundation for the rest Recording is not just a prettier report. Cypress Cloud is where the shared, duration-ordered spec queue lives, so a recorded run is what makes several machines able to cooperate on one suite at all — the queue, the history that orders it, and the run object that ties the machines together are all Cloud-side state keyed on that `projectId`. A machine running a local `cypress run` has no way to know what any other machine is doing. When a recorded run starts, Cypress prints the Cloud run URL into the CI log before the first spec executes. That line is the quickest confirmation that both halves were accepted, and it is the link you paste into a pull request when someone asks what failed.
- What happens if you edit the projectId in the Cypress config to a different value?Cypress stops being able to identify the project, so it can neither find nor add to that project's recorded runs. The run history hangs off the id, so changing it orphans everything already recorded. Unlike a record key, `projectId` is not something you rotate — if you need it out of source control, move it to the `CYPRESS_PROJECT_ID` environment variable rather than changing its value.
- A record key leaked in a build log. What do you do, and what could someone do with it?Delete that key in Cypress Cloud and create a new one; deleted keys stop working immediately, so only the stored secret changes. With the key plus the `projectId` someone can record runs into your project — adding misleading history and results your team did not produce. They cannot read your existing runs with it: the key is a write credential only.
saying these in an interview costs you the question
- Thinks the record key also grants read access to runs
- Believes projectId is a secret that must be kept out of git
- Cannot name CYPRESS_RECORD_KEY as the alternative to --key
- Suggests rotating projectId the way you rotate a key
- Puts the record key in the Cypress config file