What is a staging environment?
A staging environment is a copy of production that runs a release for final testing before it ships, with no real users. It is also called a preproduction environment. Staging runs the same build and scripts as production, with similar settings. A broken deploy script or a bad data migration then fails there, not in front of customers.
The Wikipedia article on deployment environments describes staging as an environment for testing that mirrors production as closely as possible.
Code usually passes through development and test environments first, e.g. a sandbox where a coding agent works. Staging is usually the last environment before production. A staging environment is not the Git staging area, which holds file changes before a commit. How well staging predicts production depends on environment parity, the degree to which the two environments match.
How does a staging environment work?
In a common setup, a release moves through staging in five steps:
- A change merges, and the continuous integration and delivery (CI/CD) pipeline builds one release artifact, e.g. a container image.
- The pipeline deploys that artifact to staging with staging's own hosts and secrets.
- The deploy runs the same install and migration scripts that production will run.
- Tests and people check the release in staging.
- A person or a pipeline rule approves the release, and the same artifact goes to production without a rebuild.
The checks in step 4 usually come from this set:
- Smoke tests. A quick smoke test confirms that the release starts and its main pages load.
- End-to-end tests. End-to-end testing follows key user journeys through the deployed system, e.g. checkout.
- Regression checks. Regression testing confirms that workflows from the last release still work.
- Acceptance checks. The people who asked for a change check that it meets their needs, sometimes as formal user acceptance testing (UAT). Some teams give UAT its own environment.
- Load tests. Some teams run load testing in staging, because a load test on production can slow the service for real users. The results carry over only as far as staging's servers match production's.
What is an example of a staging environment?
Here is an illustrative example. Acme Co. sells furniture online. A developer at Acme gives a coding agent the request "Let customers edit their delivery address during checkout." Orders use each customer's saved address, so the agent adds a required delivery_address column to the orders table and writes a migration.
Its tests pass in CI, where the test database starts empty. The team merges the change. The pipeline builds the merged code and deploys it to staging.shop.example.com, whose PostgreSQL database holds a masked copy of production orders. The migration fails:
Running migration 0042_add_delivery_address
ERROR: column "delivery_address" of relation "orders" contains null values
Deploy to staging failed. Production is unchanged.
The column is required, and the existing orders have no value for it. The empty CI database had no rows to fail on. The agent changes the migration so it fills delivery_address for existing orders from each customer's saved address, then makes the column required.
On the next deploy, the migration passes. A smoke test loads the store, and an end-to-end test edits an address and completes checkout. The team then promotes the same build to production.
This example is simplified. A real migration would also need a value for orders with no saved address, and a test that it can be rolled back.
What changes when a coding agent writes the code?
A coding agent usually checks its change with tests in its own workspace and in CI. Those places rarely have production's configuration or data. The Acme agent's migration passed its tests in CI, on an empty database that production does not resemble. Staging is often the first place the change runs with settings and data close to production's, and that happens after the merge.
Agents can also raise the number of changes that reach staging. A shared staging environment then holds several merged changes at once. When a check fails there, the team has to find which change caused it while the other changes wait.
An agent that holds staging credentials can also change shared data, e.g. by running a migration. Text that the agent reads can carry a prompt injection that steers those commands.
A practical adjustment is to have the agent run each migration it writes against a masked copy of production data before the merge. Keep staging and production credentials out of the agent's environment.
What are the limits of a staging environment?
Staging predicts production only as far as the two match. The Twelve-Factor App methodology says to "keep development, staging, and production as similar as possible." Teams often build both from the same scripts, but the two still drift apart. Drift often comes from these sources:
- Manual changes. Someone changes a setting or applies a hotfix in production and not in staging.
- Smaller servers. Staging runs on smaller machines to save cost, so timing and capacity differ.
- Different versions. Staging runs a different version of the database or another backing service than production.
- Test modes. Third-party services, e.g. a payment provider, run in test mode with different limits and responses.
- Stale data. The staging database is an old copy, or synthetic data that lacks the odd records production holds.
Staging has no real users, so it misses the paths that customers take and nobody scripted. It is usually shared, so it lacks test isolation, and one change's test data can break another change's checks. It also costs money and upkeep, so some small teams skip it and rely on preview environments and monitoring. A passing run in staging does not establish that the release works in production.
How is a staging environment different from production?
Production serves customers with real data, and a failure there reaches them. Staging runs the same build, and a failure there reaches only the team. Real customer data in staging is a privacy risk, so many teams load masked or synthetic data through test data management. Some problems appear only under real traffic, so teams add testing in production, e.g. monitoring after each release.
A test environment runs automated and manual tests on new builds, before the release reaches staging. A preview environment is an ephemeral environment, built for one pull request and deleted when it closes. The table compares the four environments:
| Environment | Main job | Lifetime | Data |
|---|---|---|---|
| Test environment | Runs automated and manual tests on new builds | Per run or kept running | Seeded test data |
| Preview environment | Shows one pull request to reviewers | Until the pull request closes | Seeded test data |
| Staging environment | Runs the release before it ships | Kept running and shared | Masked or synthetic data |
| Production | Serves customers | Kept running | Real customer data |
Where should agent changes run before staging?
Run an agent's change in an isolated environment first, with no access to staging or production credentials. Start the app there and try the workflow the change touches, not only its tests. Staging then checks the release as a whole.
RunStory runs your software in a separate environment, tries relevant workflows, and checks the results. It is in private alpha for CLIs and web apps. Your team keeps the final release decision.
FAQs
What is the difference between staging and UAT?
Staging is an environment, and user acceptance testing (UAT) is an activity. In UAT, the people who asked for a change try it and check that it meets their needs. Teams often run UAT in staging, and some give UAT its own environment.
Do small teams need a staging environment?
A staging environment is optional for a small team, and it costs money and upkeep. Some small teams rely on preview environments and monitoring instead. Staging still catches migrations that fail on realistic data in ways an empty test database cannot show.
Should staging use production data?
Staging should not hold raw production data, because real customer data is a privacy risk outside production. Many teams load a masked copy of production, which keeps the odd records that break migrations, or synthetic data built through test data management.
Is a preview environment a staging environment?
A preview environment is not a staging environment, although both run a change before release. A preview environment is built for one pull request and deleted when it closes. Staging keeps running between releases, is shared, and holds the release that goes to production.