Skip to content

docs: verify and fix operational facts - #172

Merged
uniqueg merged 2 commits into
mainfrom
docs/171-verify-facts
Nov 17, 2026
Merged

uniqueg merged 2 commits into
mainfrom
docs/171-verify-facts

Conversation

@uniqueg

@uniqueg uniqueg commented Nov 17, 2026 •

Copy link
Copy Markdown
Member

Summary

Verifies the operational facts of the 25 pages listed in #171 against public, read-only sources (service info and other unauthenticated GETs of the live services, the Cloud Registry API, GitHub issues, releases and repository contents via gh, and the product docs), fixes the facts that were wrong, and sets last_verified: 2026-11-17 only on the 6 pages whose facts were all checked today. No credentials were used.

Fixes

  • Poiesis (CZ): GET https://poiesis.dyn.cloud.e-infra.cz/ga4gh/tes/v1/service-info (and every other path) returns an HTML page "503 Service not available" (with HTTP 200). The page said "runs"; it now says it doesn't answer, and isn't behind the gateway or in the registry. The claim "S3 and HTTP(S), not FTP" now links to the docs section that lists the filer protocols (s3://, http(s)://, file://, inline content); the old link (Usage) doesn't list them.
  • proTES: its service info lists one backend, https://csc-tesk-noauth.rahtiapp.fi (source: configured), whose GET /ga4gh/tes/v1/tasks answers 200 without a token. The page said "the TESK of the Finnish Node"; it now names the TESK for tests at CSC, says it accepts tasks without a token, that no Node's TES service has been added yet, and that the environment is test ("proTES sandbox (BioHackathon 2026)").
  • TRS-Filer: the live service reports 0.5.1.dev13+gfa501e6dc and TRS 2.0.2; v0.5.0 reports TRS 2.0.1 (its config.yaml at the tag) and has no authentication. The data-centre tutorial is pinned to 0.5.0, so it was right about 0.5.0; the TRS-Filer page now gives the version of the deployment and the difference. trs-filer#7 (tokens for writes) and docs: send access tokens in the TES tutorials #135 (service info as a chart value, checked in deployment/values.yaml on dev) are closed as completed, so the tutorial no longer calls them merely planned: they are on the default branch and come with the next release.
  • Onboarding: Funnel runs with Slurm or OpenPBS (as the Funnel and services pages say), not Slurm only.
  • Registry: proTES and TRS-Filer aren't registered (the registry lists 4 services: GC6ZQG BIH Funnel, J0LBQG the registry, N27TBG JAN DIGITRUST TESK lab, EW7DI3 BIH WESkit). The services index and the API guide said to find their addresses there; both now say they aren't registered yet and point to their pages. (No registry-pointer work of docs: point service pages to the registry #157.) The API guide now writes the artifact as the registry does (tes, not TES).
  • Node tutorial: generic-issues#46 is closed: the ECP_CLN values are recorded there (user info only, released per client). generic-issues#32 is closed: the central Pubgrade runs on the FI Node since 2026-11-12, with only the FI TESK sidecar subscribed (more Nodes: generic-issues#34). The gaps are reworded.
  • CLI and demos: after the commit that the CLI page describes (af0e021, 2026-11-12), the GA4GH SDK got login with the OpenID Connect device flow (ga4gh-sdk#248, merged 2026-11-15; LS Login's discovery document has a device_authorization_endpoint) and the download of task logs and outputs (#188); docs: update Cloud Registry page to 1.0.0rc1 #91 (binaries) and #189 (image) are closed, and are built by release.yml on v* tags, of which there are none yet. "What's coming" and the demos row say so, instead of "Planned" and "can't log in itself yet".
  • Demos: protes-middleware-crypt4gh is archived; the row says so.

Verified and dated (2026-11-17): operators/index.md, operators/onboarding.md, operators/services/index.md, operators/services/poiesis.md, operators/services/prowes.md, operators/services/drsfiler.md.

Pages left at null, and why

Page What couldn't be verified today
demos/index.md The latest CI run of demo-tes-hybrid-cloud on main (run 43381845527, 2026-11-13) failed: a workflow input, https://www.mzv.cz/…/661666_637430_mzv_en.png, answered 404. It answers 200 again today, so the failure looks transient, but a re-run is needed before the "Current" state can be confirmed (my re-run was denied). The other repos' default branches have green CI.
researchers/federated-workflows.md Same CI run ("its CI runs it end to end").
operators/services/protes.md The access rule (group ECP_CLN:EOC-Compute, tokens issued to Krini's client) needs a token; GET /tasks without one gives 401 and the served OpenAPI requires a bearer token for every task and plugin operation.
researchers/index.md Same access rule (EOC-Compute; proTES accepts Krini's tokens).
operators/services/trsfiler.md The served OpenAPI requires a bearer token for all writes, but that the issuer is LS Login, and that the access rules match the registry's, can't be seen without a token.
partners-and-developers/apis.md Same for the issuers of proTES and TRS-Filer. Registry reads without a token, /me → 401, Swagger UI, LS Login issuer and scopes are verified.
operators/using-cloud-registry-ui.md Admins = ECP_CLN:ADMIN (needs a token). Front end, API base URL, LS Login as the only login provider (the UI redirects to login.aai.lifescience-ri.eu with scope openid profile email eduperson_entitlement), limit of 20 services and controlled types are verified.
operators/cloud-registry.md, operators/using-cloud-registry.md Admin procedures and values file (1,868 and 228 lines); the settings that the service info shows (environments, controlled, 20 per user, sync every 24 h, contactUrl, version 1.0.0rc2) match. Not checked in full. The registry's own entry J0LBQG is an imported, synced entry (serviceInfoId: ELIXIR_CLOUD_SERVICE_REGISTRY_1), not the self-listing that cloud-registry.md describes, whose ID would be ELIXIR_CLOUD_SERVICE_REGISTRY_1.
operators/node-onboarding-tutorial.md, operators/data-centre-onboarding-tutorial.md Fixed as above; the full procedures (chart values, commands) need a test deployment. Versions in their tables match the latest releases.
operators/service-info.md Product rows match (Funnel 0.12.3, Poiesis 0.2.0, calypr/funnel#1493, JaeAeich/poiesis#112, CESNET/tesp-api#62 open). Not checked in full. Note: the BIH Funnel's service info has its own id, organization and environment: prod, with version: unknown, so it seems to run a modified build; the page's statement about released Funnel still holds.
operators/ls-login.md The LS Login endpoints match its discovery document; the JupyterHub, HedgeDoc and MinIO settings and the SPREG steps weren't checked.
researchers/cli.md, researchers/tutorial-cli.md They describe SDK commit af0e021. The example output of registry list shows 2 services, the registry lists 4 today; updating it needs a build of the CLI. Moving the pages to the current SDK (with login) is a rewrite and a new test run.
researchers/krini.md, researchers/tutorial-krini.md krini#41, #43, #44, #45, #66 and cloud-components#574, which these pages name as missing features, are closed as completed. Whether the deployed Krini has them needs a login.
researchers/crypt4gh-with-protes.md Needs three VMs and an unreleased plugin (no foca-plugin-tes-data-crypt4gh release yet, as the page says).
tutorials/tes-services/interactive_services_tes.md Needs a VM and a TES service; it names the no-auth TESK, which #157 handles.

The weekly Links run opens a new "Docs pages to verify" issue for the remaining 19 pages once this one is closed.

Light lane: only docs text and front matter change; no hooks, scripts or CI. I reviewed the diff myself.

How it was verified

  • python scripts/check_names.py: OK.
  • mkdocs build --strict: built without warnings (registry table rendered from the live registry).
  • pytest: 356 passed, 100% coverage.
  • python scripts/check_verified.py: 19 pages due (was 25), exit 2 as expected.
  • Live sources, all unauthenticated GETs on 2026-11-17: service info of proTES, TRS-Filer, Poiesis CZ, CSC TESK, BIH Funnel, BIH WESkit and the registry; GET /services, /services/types, /verifications, /syncs and /me of the registry; the served OpenAPI documents of proTES, TRS-Filer and the registry; the UI's login redirect; LS Login's discovery document; gh for releases, tags, issue states, repo contents (trs-filer v0.5.0 and dev, ga4gh-sdk workflows and docs, poiesis filers) and CI runs of the demo repos.

Declined review findings

None (light lane, no reviewer subagents). Sourcery's four findings are fixed in 0848da7 and their threads resolved: the researchers' start page now says proTES forwards tasks only to the CSC test TESK for now; the onboarding table points to the caveat of the untested OpenPBS steps; the hybrid cloud row says its latest CI run failed on a third-party file; the CLI rows say the binaries and image are built for version tags.

Open questions

None.

Closes #171

🤖 Generated with Claude Code

Check the facts of the pages listed in #171 against the live services,
the Cloud Registry, GitHub and the product docs, and fix what is wrong:

- Poiesis CZ returns an error page "503 Service not available"; link
  its filer protocols instead of the usage page, which doesn't list
  them.
- proTES: its only TES service is the TESK for tests at CSC, which
  accepts tasks without a token; its environment is `test`.
- TRS-Filer: the deployment runs 0.5.1.dev13 with TRS 2.0.2; write
  tokens (trs-filer#7) and the service info value (trs-filer#135) are
  on its default branch, not just planned.
- Onboarding: Funnel also runs with OpenPBS.
- proTES and TRS-Filer aren't in the registry yet; registry artifacts
  are lower case (`tes`).
- Node tutorial: the ECP_CLN values are recorded (generic-issues#46)
  and the central Pubgrade runs (generic-issues#32).
- GA4GH SDK: login, task log downloads and release builds of binaries
  and images are on its default branch after the commit that the CLI
  page describes.
- Demos: the Crypt4GH middleware repository is archived.

Set `last_verified: 2026-11-17` on the pages whose facts were all
checked today: the operators' start page, Onboarding, the services
index, Poiesis, proWES and DRS-Filer. The other pages stay `null`: some
of their facts can't be checked without credentials or a test run.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@sourcery-ai

sourcery-ai Bot commented Nov 17, 2026 •

Copy link
Copy Markdown
Contributor

Reviewer's Guide

Documentation

Correct the documented proTES backend and deployment environment, then update the researcher-facing description to match.

  • docs/operators/services/protes.md L41-42, L48
  • docs/researchers/index.md L40-43

Update TRS-Filer deployment facts and align the onboarding tutorial with the chart’s upcoming service-info value and write-token support.

  • docs/operators/data-centre-onboarding-tutorial.md L149-150, L188-192, L331-333
  • docs/operators/services/trsfiler.md L34-35

Correct the node-onboarding guidance for LS Login group claims and the Pubgrade rollout.

  • docs/operators/node-onboarding-tutorial.md L196-200, L244-247, L462-468 (+2 small edits)

Correct onboarding platform guidance and clarify that the OpenPBS Funnel steps remain untested.

  • docs/operators/onboarding.md L17, L40

Correct Poiesis status and link to the product documentation that lists supported filer protocols.

  • docs/operators/services/poiesis.md L2-55 (4 small edits)

Clarify which services are absent from the Cloud Registry and correct the API artifact’s casing.

  • docs/operators/services/index.md L35-36
  • docs/partners-and-developers/apis.md L38, L84-85

Update the CLI documentation for SDK features and release-workflow outputs available after the documented commit.

  • docs/researchers/cli.md L581-590

Qualify demo status with current SDK capabilities, the hybrid-cloud demo’s failed CI run, and the archived Crypt4GH repository.

  • docs/demos/index.md L30-32, L102

Record the verification date for the operators’ start page.

  • docs/operators/index.md L2

Record the verification date for the DRS-Filer page.

  • docs/operators/services/drsfiler.md L2

Record the verification date for the services index.

  • docs/operators/services/index.md L2

Record the verification date for the onboarding page.

  • docs/operators/onboarding.md L2

Record the verification date for the proWES page.

  • docs/operators/services/prowes.md L2

Tips and commands

Interacting with Sourcery

  • Trigger a new review: Comment @sourcery-ai review on the pull request.
  • Continue discussions: Reply directly to Sourcery's review comments.
  • Generate a GitHub issue from a review comment: Ask Sourcery to create an
    issue from a review comment by replying to it. You can also reply to a
    review comment with @sourcery-ai issue to create an issue from it.
  • Generate a pull request title: Write @sourcery-ai anywhere in the pull
    request title to generate a title at any time. You can also comment
    @sourcery-ai title on the pull request to (re-)generate the title at any time.
  • Generate a pull request summary: Write @sourcery-ai summary anywhere in
    the pull request body to generate a PR summary at any time exactly where you
    want it. You can also comment @sourcery-ai summary on the pull request to
    (re-)generate the summary at any time.
  • Generate reviewer's guide: Comment @sourcery-ai guide on the pull
    request to (re-)generate the reviewer's guide at any time.
  • Resolve all Sourcery comments: Comment @sourcery-ai resolve on the
    pull request to resolve all Sourcery comments. Useful if you've already
    addressed all the comments and don't want to see them anymore.
  • Dismiss all Sourcery reviews: Comment @sourcery-ai dismiss on the pull
    request to dismiss all existing Sourcery reviews. Especially useful if you
    want to start fresh with a new review - don't forget to comment
    @sourcery-ai review to trigger a new review!

Customizing Your Experience

Access your dashboard to:

  • Enable or disable review features such as the Sourcery-generated pull request
    summary, the reviewer's guide, and others.
  • Change the review language.
  • Add, remove or edit custom review instructions.
  • Adjust other review settings.

Getting Help

@read-the-docs-community

read-the-docs-community Bot commented Nov 17, 2026 •

Copy link
Copy Markdown

@uniqueg
uniqueg marked this pull request as ready for review November 17, 2026 19:31
@sourcery-ai

sourcery-ai Bot commented Nov 17, 2026 •

Copy link
Copy Markdown
Contributor

Linked issues

Checked at commit 0848da7

#171 Docs pages to verify · 0 of 1 met

# Requirement Status Notes
1 Verify the operational facts on all 25 listed pages, fix inaccuracies, and set verification dates as described. 🟡 Partly met Six pages are dated, but the PR explicitly leaves 19 pages unverified or only partly checked, including pages needing authenticated checks or a test deployment.

@sourcery-ai sourcery-ai Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hey - I've found 4 issues

Prompt for AI Agents
Please address the comments from this code review:

## Individual Comments

### Comment 1
<location path="docs/operators/services/protes.md" line_range="48" />
<code_context>
 A Node's TES service is added to the configuration when its admins ask for
 it and the service requires LS Login tokens (see [Get added behind the
 gateway](../node-onboarding-tutorial.md#7-get-added-behind-the-gateway)).
+No Node's TES service has been added yet.
 The service info of proTES (`GET /ga4gh/tes/v1/service-info`) lists the TES
 services that it uses. The rest of its configuration, such as its plugins
</code_context>
<issue_to_address>
**Gateway tasks miss Node services**

When users follow the deployment-specific guidance while proTES still has only the CSC test TESK configured, `researchers/index.md` says proTES forwards tasks to Node services, but the deployment now has only the CSC test TESK configured. Users following that guidance send tasks to the test service, not a Node.

Update the researchers' guidance to distinguish the current CSC test backend from Node services that may be added later.
</issue_to_address>

### Comment 2
<location path="docs/operators/onboarding.md" line_range="40" />
<code_context>
 | Kubernetes or OpenShift | [TESK](services/tesk.md) |
 | Kubernetes | [Poiesis](services/poiesis.md) |
-| HPC or HTC (Slurm) | [Funnel](services/funnel.md) |
+| HPC or HTC (Slurm, OpenPBS) | [Funnel](services/funnel.md) |

 Follow the product docs that each page links to. When it works,
</code_context>
<issue_to_address>
**OpenPBS onboarding overstates support**

When a Node operator chooses OpenPBS from the onboarding table, the onboarding table presents OpenPBS as an ordinary Funnel option, but the Funnel page says its OpenPBS steps have not been tested and warns that failed jobs can retain their last state. The overview therefore presents an unverified path without its operational caveat.

Label OpenPBS as documented but untested in the onboarding table and point readers to the Funnel page's warning.
</issue_to_address>

### Comment 3
<location path="docs/demos/index.md" line_range="31" />
<code_context>
 | [Hybrid cloud via TES][repo-hybrid] (`demo-tes-hybrid-cloud`) | Current | A Snakemake workflow on the TES services of several Nodes, one after the other, and then on all of them through proTES. Runs on your computer with two local Funnel instances, proTES 0.6.0 and an S3 service, or on your own services. | [Run Workflows Across Nodes](../researchers/federated-workflows.md) |
</code_context>
<issue_to_address>
**Demo appears confirmed working**

When the latest CI run has failed and no successful rerun has confirmed the demo works, the hybrid-cloud row stays marked Current, which the page defines as working as described, so readers are told the demo works without confirmation.

Qualify the status or update it after a successful rerun.
</issue_to_address>

### Comment 4
<location path="docs/researchers/cli.md" line_range="587-588" />
<code_context>
+| Ready-made binaries, without Rust | Built by the release workflow on the default branch ([ga4gh-sdk#91](https://github.com/ga4gh/ga4gh-sdk/issues/91)); none published yet, as the SDK has no release yet. |
</code_context>
<issue_to_address>
**Release workflow trigger unclear**

The issue description says the release workflow builds binaries and images on `v*` tags, but these rows say they are built by a workflow “on the default branch.” Clarify that the workflow is present on the default branch and produces artifacts for release tags.
</issue_to_address>

Sourcery assessment

Approval pending. 3 findings to address first.

Blocking findings: docs/operators/services/protes.md:48, docs/operators/onboarding.md:40, docs/demos/index.md:31


Sourcery is free for open source - if you like our reviews please consider sharing them ✨

Comment thread docs/operators/services/protes.md Resolved
Comment thread docs/operators/onboarding.md Resolved
Comment thread docs/demos/index.md Resolved
Comment thread docs/researchers/cli.md Resolved
- Researchers: proTES forwards tasks only to the CSC test TESK for now.
- Onboarding: point to the caveat of the untested OpenPBS steps.
- Demos: say that the hybrid cloud demo's latest CI run failed on a
  third-party file.
- CLI: binaries and the image are built for version tags.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@uniqueg
uniqueg merged commit 1e81aca into main Nov 17, 2026
13 checks passed
@uniqueg
uniqueg deleted the docs/171-verify-facts branch November 17, 2026 20:04
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Docs pages to verify

1 participant