Developer Resources

Site Admin Workflow

Responsibilities and procedures for the site administrator role.

Responsibilities

1. 1.Assigning reviewers (peer, Lead Civil, Director) at each stage transition
2. 2.Running checkpoint deploys for Lane 1 PRs
3. 3.Running or coordinating the technical edit
4. 4.Preparing final merge commits (flipping the draft flag, updating version history)
5. 5.Merging PRs and approving production deploys
6. 6.Handling Lane 4 (editorial fix) and Lane 5 (dev doc) PRs as sole reviewer
7. 7.Resolving edge cases

Daily routine

The site administrator monitors PRs that need attention. The stage progression workflow tags @usace-rmc/docs-admin at every transition. A useful filter is is:open label:"stage:ready-to-merge" or is:open review-requested:@me.

Assigning reviewers

Reviewers are assigned ad-hoc per PR via the Reviewers sidebar (gear icon → type username → select). There are no standing review teams for peer reviewers or Lead Civils. The workflow's transition comment identifies which role to assign next.

For Lane 1, the site administrator assigns up to three people across the lifecycle: the peer reviewer (if the author did not), the Lead Civil after peer approval, and the Director after the technical edit.

Per-individual gating. When the site administrator assigns someone via the Reviewers sidebar, the stage progression workflow records that person in a hidden state comment on the PR, keyed by the current review stage. Only approvals from those assigned reviewers advance the stage — drive-by approvals from other team members are logged but ignored by the workflow. Multiple people can be assigned at the same stage; the first approval from any of them advances the PR.

To replace an assigned reviewer, the site administrator removes them from the Reviewers sidebar and adds the correct person. The state comment updates automatically.

Running a checkpoint deploy (Lane 1)

After the author marks the technical edit complete (the PR advances to stage:director-review), the site administrator deploys the PR branch to the live site (watermarked) for the Director's review.

1. 1.In the repo, navigate to the Actions tab and click Deploy to GitHub Pages in the sidebar.
2. 2.Click the Run workflow dropdown (upper right).
3. 3.Enter the PR branch name in the ref field.
4. 4.Click Run workflow.
5. 5.When the build completes, click Review deployments → check production → Approve and deploy.
6. 6.Verify the document on the live URL with the watermark.
7. 7.Post a comment on the PR with the live URL so the Director knows where to read.

This is the first time the document appears on the live site. The peer review, Lead Civil review, and technical edit all happened earlier on the preview URL or against source files; the live deploy is deferred until the document has passed editorial review.

The site administrator re-deploys whenever the author pushes revisions during Director review, posting a comment noting the update.

Running the technical edit

After the preceding review stage approves (the PR advances to stage:ai-editor-review), the site administrator runs the AI-assisted technical edit against the PR. If the necessary tooling is not available locally, the site administrator coordinates with a team member who has it. No deploy is required at this stage — the technical edit reads the source MDX directly.

The AI posts inline review comments. The author addresses them and checks the PR description checkbox to advance the PR, at which point (Lane 1) the site administrator runs the checkpoint deploy.

See Technical Edit for the full prompt the AI uses.

Manual override. If a human technical editor performed the review instead, or the author is unavailable to check the checkbox, the site administrator applies the admin:advance-to-director label to the PR. The workflow removes the label and advances the stage the same as a checkbox event, then posts the next-stage instructions.

Preparing the final merge

When a PR reaches stage:ready-to-merge, the site administrator prepares and executes the merge.

1. 1.Check out the PR branch locally or via github.dev.
2. 2.In src/docConfig.js, change the document's draft flag from true to false. If the document is going active for the first time, also flip active: true.
3. 3.Update 00-version-history.mdx with reviewer and approver names.
4. 4.Commit and push.
5. 5.Merge the PR to main.
6. 6.Approve the final production deploy in the Actions tab.

Version history fields are populated by lane.

Lane	reviewedBy	approvedBy
Lane 1 (new document)	Peer reviewer and Lead Civil	Director
Lane 2 (major revision)	Peer reviewer and Lead Civil	-
Lane 3 (minor revision)	Peer reviewer	-
Lanes 4 and 5	N/A	N/A

The review-workflow commit status

Every documentation PR has a review-workflow commit status that branch protection on main requires to be success before the PR can merge. This is the hard merge gate — no participant, including the site administrator, can click the merge button until the bot flips this status to success. The bot manages the status automatically.

Situation	Status
stage:peer-review / stage:lead-civil-review / stage:ai-editor-review / stage:director-review	pending
stage:needs-lane (workflow could not detect the lane)	pending
stage:ready-to-merge (all reviews complete)	success
lane:editorial-fix or lane:dev assigned	success (immediately)
Non-docs PR, CI Build passed	success

If a PR is stuck because review-workflow is pending, the stage label indicates what review is outstanding. If a PR is stuck because review-workflow is missing entirely (never got set), lane detection probably failed — the site administrator applies a lane:* label manually to re-trigger the workflow.

Approving deploys

Every deploy pauses at the production environment gate. The site administrator receives an email. Navigating to Actions → the workflow run → Review deployments → check production → Approve and deploy releases the deploy.

A Lane 1 document may involve multiple deploys: one checkpoint after the technical edit completes (for Director review), optional re-deploys during Director review if the author pushes fixes, and one final deploy after merge.

Handling Lane 4 and Lane 5 PRs

Lane 4 (editorial fix) and Lane 5 (dev doc) PRs skip formal review. The site administrator is the reviewer, approver, and merger.

1. 1.Click the preview URL to see the change.
2. 2.Review the Files changed tab.
3. 3.Approve, merge, and approve the deploy.

The review-workflow commit status flips to success immediately on lane assignment, so the merge button is enabled as soon as CI finishes.

Edge cases

Situation	Resolution
Wrong lane	Remove the current lane:* label and apply the correct one; the workflow re-initializes.
Branch starts with docs/ but does not match a sub-prefix	The workflow applies stage:needs-lane and tags the site administrator; the administrator applies the correct lane:* label.
Documentation change pushed to a non-docs/ branch	The workflow intercepts at PR open time regardless of branch name because it detects changes under docs/. Content entirely under docs/dev/ auto-assigns lane:dev. Otherwise the workflow applies stage:needs-lane and tags the administrator to assign the correct lane manually.
Non-documentation PR with no lane comments	Expected behavior. PRs that do not touch docs/ are silently skipped by the lane workflow and pass review-workflow via CI Build. This is normal for infrastructure, tooling, and dependency PRs.
Unresponsive reviewer	Ping them on the PR, or remove them from the Reviewers sidebar and assign someone else. The state comment updates automatically.
Drive-by approval from an unassigned reviewer	The workflow posts a note logging the approval but does not advance the stage. To use that approval, add the approver via the Reviewers sidebar and ask them to re-approve.
Author pushes new commits during an active review	Normal and expected. The workflow does not reset the stage. The bot re-sets the review-workflow commit status on the new head SHA and pings the assigned reviewer(s) to backcheck.
Stale checkpoint deploy	Re-run the checkpoint deploy and post a comment.
Build fails on checkpoint deploy	Coordinate with the author to fix the branch.
Build fails after merge to main	Push a hotfix to main or revert the merge. Re-run the deploy. Note that deploy.yml filters by paths — a merge that does not touch site-affecting files does not trigger a redeploy.
Need to force a production redeploy	Actions → Deploy to GitHub Pages → Run workflow, specify the ref (usually main), and approve at the production gate. This is the escape hatch when the path filter would otherwise skip a merge that needs to ship.

Onboarding new site administrators

1. 1.Clone the repo and confirm a local build succeeds.
2. 2.Read Documentation Guide chapters 09 through 15.
3. 3.Shadow an existing administrator through one full PR lifecycle.
4. 4.Practice on a Lane 4 editorial fix PR.