SARtale Guide

Lake requests

A visitor asks for a lake by opening a GitHub issue. A workflow checks it and counts NISAR passes over the point from NASA's CMR catalogue, and a team member decides. There is no request server and no database: the issues are the record. NISAR data are downloaded only after the team accepts a lake.

How a request goes#

  1. On the story page, the visitor fills in the "Add a lake" form and presses Request a lake. The website checks the input first (see Rules), then opens GitHub's Add a lake issue form with the fields filled in: Lake name, Latitude (°N), Longitude (°E) and Where the coordinates come from.
  2. The visitor presses Submit new issue. A GitHub sign-in is needed. The issue gets the label lake-request.
  3. The lake-request.yml workflow reads the issue, applies the rules, counts NISAR passes over the point, comments with the result and sets a label.
  4. A team member adds the label accepted. The lake-accept.yml workflow adds the lake to processing/lakes_in.json, searches, fetches and builds, runs the tests, commits the data, redeploys the site, comments "Accepted. The lake is now watched: …" with a link, and closes the issue.
  5. To turn a request down, a team member closes the issue without accepted.

Anyone can request a lake. The repository is public, so any visitor signed in to GitHub can open a request issue.

Rules#

RuleValue
Point34.4–37.6 °N, 70.8–76.6 °E (Gilgit-Baltistan and upper KP)
Name2–80 characters, and none of the phrases SARtale never uses (such as "safe" or "early warning"; the list is BANNED_CLAIMS in app/src/content.ts). Such a name is refused with: "The name uses a phrase SARtale does not use ("safe"); please use the lake's usual name."
Source3–200 characters: an inventory, a paper, a field survey or a dated map. The source becomes the lake's coord_source in lakes.json, so the same phrases are refused, with: "The source uses a phrase SARtale does not use ("safe"); please describe where the coordinates come from."
DistanceA point within 1 km of a watched lake or of another request is refused, and the message names that lake. The earlier issue wins
Open requestsAt most 200. Past that, new requests are marked invalid with "The request list is full; try again later."

The website runs the same checks before it opens the issue, but the workflow checks again. An issue that breaks a rule is labelled invalid, gets a comment that starts "This request cannot be used." with the reason, and is closed.

Labels#

LabelMeaningSet by
lake-requestThe issue is a lake requestThe issue form
searchedThe point passed the rules and has at least 3 NISAR passes. The comment gives the passes, the tracks and the first and last datesWorkflow
too few passesThe point is valid but has fewer than 3 NISAR passes, so there is no trend yet. The team can still accept itWorkflow
acceptedA team member approves the lake. This starts the rebuildA team member
rebuild failedThe rebuild did not finish, or NASA's catalogue did not answer. Nothing was publishedWorkflow
invalidA rule was broken. The issue is closedWorkflow
rejectedThe team closed the request without acceptedWorkflow

Who can accept#

Only someone with write, maintain or admin access to the repository. The check looks at the account that added the label, not at the issue author. If anyone else adds accepted, no rebuild runs: the workflow removes the label and comments "Only the SARtale team can accept a request." If the workflow cannot tell who added the label or when, or GitHub does not answer the permission check (it is tried twice), it also removes the label, and comments "SARtale could not check who added the label; a team member can add it again."

The rebuild runs in separate jobs so that no job holds both the Earthdata login and a write token:

  • Rebuild has the Earthdata login (the earthdata environment) and read-only access. It adds the lake, searches, fetches, builds and runs the tests, then hands the data over as an artifact.
  • Publish has a write token and no Earthdata login. It checks the artifact, commits the data, redeploys, comments and closes the issue. It refuses data built from other method code, configuration, outlines, Sentinel-2 check rows, environment or rebuild steps than main has now, and starts the accept again instead. It checks this twice: when it installs the data, and again after it rebases its commit onto the newest main, just before it pushes.

Only one rebuild runs at a time, shared with the weekly refresh. A second accept waits and is started when the first is done. If the data on main change during a rebuild, it starts itself again, at most 3 runs in all.

If the request changes after approval#

An approval covers the name, coordinates and source the team saw. If the visitor edits the issue afterwards, the approval is withdrawn: the workflow removes accepted and comments "This request changed after it was approved. A team member must accept it again."

The rebuild takes a while, so just before it publishes, the workflow reads the issue again. It publishes only if the issue is still open, still carries accepted from the same team member at the same time, that person still has write access to the repository, and the issue still has the values the rebuild used. If not, nothing is published and the issue gets a comment saying which of these changed. When the values were edited or the approver lost access, accepted is removed too, so a team member adding it again starts a fresh check.

A request labelled accepted before this system was deployed is refused once, with "This request was approved before the new check existed. A team member must accept it again."

Rejecting#

Close the issue without adding accepted. The workflow labels it rejected. The reason shown on the website is the team's last comment on the issue, cleaned of control characters and cut to 200 characters. Write that comment for the visitor.

What the bot comments#

WhenComment
3 or more passes"Checked against NASA's catalogue: 14 NISAR passes over this point on 2 tracks, 2026-06-18 to 2026-10-23. The team decides whether this lake is watched."
Fewer than 3 passes"Checked against NASA's catalogue: 1 NISAR pass over this point, fewer than the 3 needed for a trend. The team still decides whether this lake is watched."
Rule broken"This request cannot be used." and the reason
Catalogue down"NASA's catalogue did not answer; the team will retry." The next run checks again
Accepted"Accepted. The lake is now watched:" and a link to the lake on the site
Published, deploy not started"Published, but the site deploy did not start; run the Deploy workflow." The lake is on main; run Actions → Deploy to GitHub Pages → Run workflow
Rebuild failed"The rebuild failed; see" a link to the run, then "Nothing was published."

The state label marks that a comment was sent, so a lost comment is sent again on the next run and a delivered one is not repeated.

requests.json#

The website reads app/public/data/requests.json to show requested lakes on the map and to check the form. The lake-request.yml workflow keeps it up to date, on every issue event and once a day at 04:17 UTC, and commits it. Each entry has the issue number, name, point, state, passes, tracks, first and last date, a reason and the creation time. The daily run also starts waiting approvals again, one at a time, so an accept that was dropped is not lost.

StateMeaning
searched, too_few_passesChecked and waiting for the team
check_failedThe catalogue did not answer; it is tried again
acceptedAdded to the register
invalid, rejectedNot used; the reason is given

Commands the workflows run#

You rarely run these by hand. From processing/:

conda run -n sartale python -m sartale.run_pipeline lake-issues --help
conda run -n sartale python -m sartale.run_pipeline lake-issue-accept --help

lake-issues checks every request and writes requests.json and the comments and labels to apply. lake-issue-accept appends one entry to lakes_in.json with role watch and a coord_source naming the request. To add a lake without an issue, see Add a lake by hand.

Check the source first. Accept a lake only when its coordinate has a source someone can check: an inventory, a paper, a field survey or a dated map.