What you will take away from this lesson
Lesson 1001 left ACME with a site only its builders can open. This lesson gives it the environments other people use, moves a release into them, and takes one back out again.
The model is one sentence: agents work in dev, and people use what was promoted. Everything in this lesson is a consequence of that sentence, and it is the reason an organization can let an agent maintain a public website.
Learning Objectives
- 01State the three rules every site follows and what each one prevents.
- 02Place a review environment between dev and prod and say what a new one starts as.
- 03Promote a release one step at a time and explain why a promotion copies and rebuilds nothing.
- 04Follow a promotion through approval and say what the approver sees.
- 05Read the refusal a publish aimed at a live environment gets.
- 06Roll an environment back and say which releases it keeps to return to.
Where this lesson sits
Lesson 1001 published release 1 of acme-stores into dev. Since then the agent corrected the Sunday opening hours on the store finder, which made release 2. Both live in the working copy, where only the people building the site can see them.
1000 Series: Sites
- 1001Your first siteWhat a site is, the working copy called dev, the first release, the address it answers at, and who may create one.
- 1002Dev, promote, roll backEnvironments people use, promotion of the exact release that was reviewed, approval, rollback, and the history of every move.
- 1003Private environments, public domainsAccess per environment: people, personas, everyone internal, the sign-in every pages address asks for, and the rules for making a domain public.
- 1004Your own domainThe main address, an address for every environment, adding a domain in the portal, making it public, and the names a site cannot take.
- 1005Layouts and recordsLayouts, includes and records: the agent maintains data and the platform generates pages, paged lists and category indexes.
- 1006Editing a live siteReading and patching site files in place, dry runs and diffs, overlays for new files, and one promotion for several edits.
- 1007Capstone: moving an existing site onto PlexaraA crawl that keeps every address, redirects as rules, forms replaced by Plexara forms, and the whole series end to end.
The 1000 series builds on the forms and endpoints of the 700 series and the sharing model of the 800 series: a site is where the pages people open live, with the same people, personas and approvals deciding who reaches them.
Agents work in dev. People use what was promoted.
Every site on Plexara follows three rules. They are not settings and no role is exempt from them. Together they draw one line through the site: on one side, a working copy where anything can change and nobody depends on it; on the other, the environments people use, where nothing changes except by a deliberate move.
The line is what lets an organization hand a website to an agent. The agent is fast, tireless and occasionally wrong. Behind the line, being wrong costs nothing.
The three rules of every site
- 1
Changes land in dev
Every publish, every in-place edit and every overlay writes a new release into dev and nowhere else, whether a person or an agent makes it. dev is the working copy: nothing anyone relies on is served from it.
- 2
Promote what is ready
Promote points the next environment at the exact release the one before it serves: dev to stage, stage to prod. The files are not rebuilt, re-rendered or copied on the way. What was reviewed is what goes live, byte for byte.
- 3
The environments people use are read-only
stage, prod and every other environment move only by Promote and Roll back, with approval where the environment requires it. A publish or an edit aimed at one is refused, for an administrator as much as for an agent.
The portal prints the first two at the top of every site’s Environments tab, under How this site works, beside the rule for who opens each address that lesson 1003 covers. An agent reads the same rules in the platform’s own guidance before it builds a site, so the person and the agent start from the same model.

The environments people use
A new site has dev and prod. Any environment a release should pass through on its way to prod goes between them. ACME wanted one, a stage for review by people outside the web team, and it wanted approval required before anything reaches prod.
Placing stage between dev and prod, and requiring approval on prod
What the agent calls. This is the exchange the agent has with Plexara on your behalf, shown for the technical reader. You ask in plain language; you never type any of it.
→ manage_site
{ "command": "set_environment", "site": "acme-stores", "environment": "stage",
"after": "dev" }
← { "status": "done",
"site": { "name": "acme-stores", "environments": [
{ "name": "dev", "release": 2 },
{ "name": "stage", "release": 0 },
{ "name": "prod", "release": 0 } ] } }
→ manage_site
{ "command": "set_environment", "site": "acme-stores", "environment": "prod",
"requires_approval": true }
← { "status": "done",
"site": { "name": "acme-stores", "environments": [
{ "name": "dev", "release": 2, "requires_approval": false },
{ "name": "stage", "release": 0, "requires_approval": false },
{ "name": "prod", "release": 0, "requires_approval": true } ] } }A new environment serves no release and goes after the environment it names: dev, or one already between dev and prod. dev is always first and prod always last, and every list of the site’s environments follows that order. In the portal this is New environment above the environment cards, which draws the order it will make, and Move on a card places an environment somewhere else later. The names between dev and prod are yours: a site can pass a release through stage, then client-review, on its way to prod.
Promoting a release
Promote points an environment at a release. Jordan Reyes, who manages the site with Grace, asked the agent to promote dev to stage, read the site at stage’s address, and then asked for stage to go to prod.
Promoting release 2 to stage, then to prod through approval
What the agent calls. This is the exchange the agent has with Plexara on your behalf, shown for the technical reader. You ask in plain language; you never type any of it.
→ manage_site
{ "command": "promote", "site": "acme-stores", "from": "dev", "to": "stage" }
← { "environment": "stage", "release": 2, "status": "promoted",
"address": "https://acme-stores--stage.pages.example.com/" }
→ manage_site
{ "command": "promote", "site": "acme-stores", "from": "stage", "to": "prod",
"reason": "Store finder with corrected Sunday hours, reviewed on stage" }
← { "environment": "prod", "release": 2, "status": "awaiting_approval",
"approval": { "purpose": "site_promote", "site_name": "acme-stores",
"target": "prod", "version": 2, "status": "pending",
"requester_email": "[email protected]" } }
... an administrator approves the request in Approvals ...
→ manage_site
{ "command": "promote", "site": "acme-stores", "from": "stage", "to": "prod" }
← { "environment": "prod", "release": 2, "status": "promoted",
"address": "https://acme-stores--prod.pages.example.com/" }The first promotion takes effect at once. The second waits, because prod requires approval and the person asking is not an administrator. The request names the release by the digest of its files, so the approval is for exactly those files and nothing that might be published afterwards. Once it is approved, the same promotion goes through.
Promotion goes one step. prod takes a release only from stage, and only the release stage serves. Asked to promote dev straight to prod, the platform refuses and names stage, so nothing reaches prod without having been served on stage first.
When a promotion needs approval
Whether a promotion needs approval is decided by the environment it is going to. That keeps the control with the address people rely on, whoever happens to be doing the work that day and whichever agent they are using.
A promotion that requires approval
What is asked
- One release of one site, to one environment, with the reason the requester typed. The request is fixed to the digest of the release’s files.
What the approver sees
- The files changed, added and removed against the release the environment serves now, and the redirects added. The same summary appears on Promote, so the person asking has read what the approver will read.
Who approves
- An administrator, in the portal’s Approvals section. An administrator promoting to an environment that requires approval records their own approval in the same step, so the record never has a gap.
What approval does not do
- It moves nothing by itself. The requester promotes again and the release goes live. A release the approver never saw can not ride in on the approval, because a different release has a different digest.
Approval is a setting on the environment, so it follows the address people rely on and not the person doing the work. ACME requires it on prod and leaves stage open, which is the usual shape: fast review, deliberate release.

The environments people use cannot be edited
Sooner or later someone asks the agent to fix a typo on the live site, right now, skipping the review. The platform’s answer is the same for everyone.
A publish aimed at prod is refused
What the agent calls. This is the exchange the agent has with Plexara on your behalf, shown for the technical reader. You ask in plain language; you never type any of it.
→ manage_site
{ "command": "publish", "site": "acme-stores", "environment": "prod",
"files": [ { "path": "index.html", "content": "<!doctype html> ..." } ] }
← environment "prod" is read-only: publish, patch and edits change dev,
and a release reaches prod by promoteThe refusal tells the agent what to do next, and the agent does it: publish to dev, ask for a review, promote. No role lifts the rule. An administrator’s publish to prod is refused with the same sentence, because the rule protects the people using the site and not the platform from its users.
Rolling back
A review can miss something. The remedy for a bad release is not a hurried fix published over the top of it. It is the previous release, which is still there.
Rolling prod back from release 3 to release 2
What the agent calls. This is the exchange the agent has with Plexara on your behalf, shown for the technical reader. You ask in plain language; you never type any of it.
→ manage_site
{ "command": "rollback", "site": "acme-stores", "environment": "prod" }
← { "environment": "prod", "release": 2, "status": "rollback",
"address": "https://acme-stores--prod.pages.example.com/" }Release 3 added a holiday-hours banner with the wrong closing time. It was reviewed on stage, promoted, and wrong anyway. One call puts prod back on release 2, and the next visitor gets the earlier page. dev and stage stay on release 3, where the fix is made.
Roll back returns to the newest earlier release that environment served, or to a release you name that it served before. A release it has served has already been through whatever the environment requires, so rolling back asks for no new approval. A release it never served is reached by Promote.
Each environment keeps the last 50 releases it served, and the owner or an administrator can raise or lower that number for one environment or keep every release. A release no environment keeps is removed by a daily cleanup, and from then on it can no longer be rolled back to. Its record stays in the history.
An environment is a pointer
Laid out step by step, the whole lesson is three pointers moving across three releases.
Which release each environment serves, step by step
| Step | dev | stage | prod |
|---|---|---|---|
| Release 2 published: Sunday hours corrected | 2 | none | none |
| Promote dev to stage | 2 | 2 | none |
| Promote stage to prod, approved | 2 | 2 | 2 |
| Release 3 published: holiday-hours banner | 3 | 2 | 2 |
| Promote dev to stage, then stage to prod | 3 | 3 | 3 |
| Roll back prod | 3 | 3 | 2 |
Three environments, three releases, six steps, and no file was copied after it was published. An environment is a pointer at a release. Promote and Roll back move the pointer, the move is recorded, and the site answers from the new release on the next request.
What a promotion guarantees
The record
Every release and every move is kept, and the portal shows both. A question about the site’s past, such as what was live on the first of the month or who promoted the banner, has an answer on the record.
What the portal keeps about every release and every move
Releases
- Every release with its number, its note, where its files came from, how many files and how large, who published it and when, and which environments serve it now. A release no environment keeps any longer is marked as removed.
One release
- Its files with their types and sizes, filterable by path, and its redirect rules. Open site goes to the environment serving it.
History
- Every move of every environment: publish, promote or roll back, the release it moved from and to, who did it and when. Filter it to one environment to read that address’s whole life.
The same records answer the agent. Ask what changed on the public site last week and it reads the moves and the releases rather than guessing from the pages. Every call that changes a site is also in the audit log beside the rest of the platform’s activity (Governance).


What comes next
ACME’s site now has three environments, and every address of all three asks for a sign-in. Lesson 1003 shares stage with a supplier and with everyone inside ACME, and sets out what it takes for an address to answer anyone.
Key terms
Five terms cover how a release reaches the people who use a site.
Key Terms
- Promote
- Point an environment at the release the environment before it serves, one step at a time. Copies no file and takes effect on the next request.
- Roll back
- Point an environment at a release it served before and still keeps: the newest earlier one, or one you name. Needs no new approval.
- Requires approval
- A setting on an environment. A promotion to it by anyone but an administrator waits in Approvals, fixed to the release’s digest.
- Read-only environment
- Every environment but dev. It moves only by Promote and Roll back, and refuses a publish or an edit from anyone.
- History
- The record of every publish, promote and roll back on a site, by environment, release and person.
