Skip to main content
Architecture10 min read

1002 - Dev, promote, roll back

Agents change dev and nothing else. People promote the exact release they reviewed, one environment at a time, to the environments other people use, and roll back by pointing an environment at a release it served before. A release is an immutable set of files, so a promotion copies nothing, rebuilds nothing, and takes effect at once.

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

  1. 01State the three rules every site follows and what each one prevents.
  2. 02Place a review environment between dev and prod and say what a new one starts as.
  3. 03Promote a release one step at a time and explain why a promotion copies and rebuilds nothing.
  4. 04Follow a promotion through approval and say what the approver sees.
  5. 05Read the refusal a publish aimed at a live environment gets.
  6. 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

Open index

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. 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. 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. 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.

A site's Environments tab: a How this site works panel with three steps, Changes land in dev, Promote one step at a time, and Only a domain you make public opens for anyone, then Main address, Add domain and New environment buttons above three environment cards, dev, stage and prod, each with its release and addresses, prod marked Public domain and Requires approval.
A site's Environments tab. The rules sit above the environment cards, which run in promote order: dev, stage, prod.

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 Approvals section with a Status filter set to Pending and one request: who asked and when, the reason they gave in quotes, a summary of what changed since the version approved before, a Preview button, a comment box for the requester, and Approve and Deny buttons.
The Approvals section, here holding a request about a form. A site promotion and a request to make a domain public wait in the same queue, a promotion with the files and redirects its release carries.

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 promote

The 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

Stepdevstageprod
Release 2 published: Sunday hours corrected2nonenone
Promote dev to stage22none
Promote stage to prod, approved222
Release 3 published: holiday-hours banner322
Promote dev to stage, then stage to prod333
Roll back prod332

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).

A site's Releases tab: a table of three releases with number, note, source archive, file count, size, who published it and when, and a badge for the environment each is serving in: dev, stage and prod.
The Releases tab. Each release carries its note and shows which environment serves it now.
A site's History tab with an All environments filter and three rows: a Publish on dev from release 11 to 12, a Promote on prod from release 8 to 9, and a Roll back on prod from release 9 to 8, each with the person who made it.
The History tab records every move of every environment: publish, promote and roll back, with the releases it moved between and who made it.

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.