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#
- 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.
- The visitor presses Submit new issue. A GitHub sign-in is needed. The issue gets the label
lake-request. - The
lake-request.ymlworkflow reads the issue, applies the rules, counts NISAR passes over the point, comments with the result and sets a label. - A team member adds the label
accepted. Thelake-accept.ymlworkflow adds the lake toprocessing/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. - 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#
| Rule | Value |
|---|---|
| Point | 34.4–37.6 °N, 70.8–76.6 °E (Gilgit-Baltistan and upper KP) |
| Name | 2–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." |
| Source | 3–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." |
| Distance | A 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 requests | At 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#
| Label | Meaning | Set by |
|---|---|---|
lake-request | The issue is a lake request | The issue form |
searched | The point passed the rules and has at least 3 NISAR passes. The comment gives the passes, the tracks and the first and last dates | Workflow |
too few passes | The point is valid but has fewer than 3 NISAR passes, so there is no trend yet. The team can still accept it | Workflow |
accepted | A team member approves the lake. This starts the rebuild | A team member |
rebuild failed | The rebuild did not finish, or NASA's catalogue did not answer. Nothing was published | Workflow |
invalid | A rule was broken. The issue is closed | Workflow |
rejected | The team closed the request without accepted | Workflow |
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
earthdataenvironment) 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#
| When | Comment |
|---|---|
| 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.
| State | Meaning |
|---|---|
searched, too_few_passes | Checked and waiting for the team |
check_failed | The catalogue did not answer; it is tried again |
accepted | Added to the register |
invalid, rejected | Not 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.
SARtale Guide