Repository navigation
Add API reference and Software development tools integrations guide - #1673
Merged
Merged
Conversation
Registers flyteplugins-{github,slack,jira,clickup,linear} in
api-packages.toml and commits their generated API reference.
The five are a family, not five unrelated plugins: each contributes one
`Provider` to the receiver in `flyte.extras.webhooks`, which ships with
flyte and is already documented with the SDK. So they are grouped under a
nested output_folder the way the agents adapters are, sharing one
explanatory landing page, rather than flattened into five siblings at the
top of the integrations base.
`name` stays flat (saas-<product>) because it names the linkmap file,
which lives in a single flat directory; page URLs follow output_folder.
No `extras` on any entry: github's `review_pr` and
`mint_installation_token` import PyGithub and PyJWT lazily, so the parser
imports the package without the [review] and [auth] extras installed.
Signed-off-by: Niels Bantilan <niels.bantilan@gmail.com>
A section rather than five flat pages, following the agents/ precedent: the five providers share one model -- the normalized event, run_once, the scope allowlist, the dashboard -- and documenting that five times would be both repetitive and the thing most likely to drift. `_index.md` carries the shared half, including the parts that are only learnable the hard way: - events with no scope are acknowledged but never dispatched, which presents as "my webhook is not firing"; - two simultaneous deliveries of one event can both launch, because the label check is a read followed by a launch; - handlers must await run_once.aio, since the blocking form stalls the event loop and GitHub times out in ten seconds. Per-product pages carry the setup steps, the full event-constant tables, and each product's quirks: GitHub's two content types normalizing identically, Slack's three delivery shapes on one route and its two non-interchangeable credentials, Linear's nested team id, ClickUp's single-string event names, Jira's lack of signing. The Jira page states plainly what the shared-token substitution does not give you, and says not to reach for require_signature=False to make deliveries flow. Nothing else in the docs would tell a reader that before they shipped it. Also adds a "Not to be confused with" section: FlyteWebhookAppEnvironment exposes Flyte's own operations outbound, WebhookAppEnvironment receives inbound. Similar names, opposite directions. Code is embedded from the examples added in unionai-examples #319-323, so the published snippets are the tested source. HMAC goes in the shared cspell dictionary; it is RFC 2104, not a coinage. Signed-off-by: Niels Bantilan <niels.bantilan@gmail.com>
cosmicbboy
requested review from
EngHabu,
kumare3,
ppiegaze and
samhita-alla
as code owners
October 2, 2026 04:25
Contributor
There was a problem hiding this comment.
Copilot review overview
🟡 Changes recommended
ClickUp verification uses an incompatible header, while several passages overstate verification and deduplication guarantees.
Review effort: Balanced
Findings: 3
Open (10)
What changed in this PR
Adds documentation and generated API references for five SaaS webhook plugins.
Changes:
- Registers and documents GitHub, Slack, Jira, ClickUp, and Linear plugins.
- Adds shared and provider-specific integration guides.
- Generates API references and autolinker maps.
| File | Description |
|---|---|
.cspell-project-words.txt |
Adds HMAC terminology. |
api-packages.toml |
Registers five SaaS plugins. |
content/integrations/_index.md |
Adds the SaaS category. |
content/integrations/saas-integrations/_index.md |
Documents the shared webhook model. |
content/integrations/saas-integrations/github.md |
Adds the GitHub guide. |
content/integrations/saas-integrations/slack.md |
Adds the Slack guide. |
content/integrations/saas-integrations/jira.md |
Adds the Jira guide. |
content/integrations/saas-integrations/clickup.md |
Adds the ClickUp guide. |
content/integrations/saas-integrations/linear.md |
Adds the Linear guide. |
content/api-reference/integrations/saas-integrations/_index.md |
Adds the API landing page. |
content/api-reference/integrations/saas-integrations/github/_index.md |
Generates GitHub APIs. |
content/api-reference/integrations/saas-integrations/github/githubprovider.md |
Documents GitHubProvider. |
content/api-reference/integrations/saas-integrations/github/reviewcomment.md |
Documents ReviewComment. |
content/api-reference/integrations/saas-integrations/github/reviewcontext.md |
Documents ReviewContext. |
content/api-reference/integrations/saas-integrations/github/reviewdecision.md |
Documents ReviewDecision. |
content/api-reference/integrations/saas-integrations/slack/_index.md |
Generates Slack APIs. |
content/api-reference/integrations/saas-integrations/slack/slackprovider.md |
Documents SlackProvider. |
content/api-reference/integrations/saas-integrations/jira/_index.md |
Generates Jira APIs. |
content/api-reference/integrations/saas-integrations/jira/jiraprovider.md |
Documents JiraProvider. |
content/api-reference/integrations/saas-integrations/clickup/_index.md |
Generates ClickUp APIs. |
content/api-reference/integrations/saas-integrations/clickup/clickupprovider.md |
Documents ClickUpProvider. |
content/api-reference/integrations/saas-integrations/linear/_index.md |
Generates Linear APIs. |
content/api-reference/integrations/saas-integrations/linear/linearprovider.md |
Documents LinearProvider. |
linkmap/saas-github-linkmap.json |
Maps GitHub API symbols. |
linkmap/saas-slack-linkmap.json |
Maps Slack API symbols. |
linkmap/saas-jira-linkmap.json |
Maps Jira API symbols. |
linkmap/saas-clickup-linkmap.json |
Maps ClickUp API symbols. |
linkmap/saas-linear-linkmap.json |
Maps Linear API symbols. |
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
Deliberate pointer bump, not a side effect: this is what makes the
`{{< code >}}` references on the new SaaS integration and lifecycle pages
resolve, so it belongs with them rather than in a later sweep.
fee0dae..7b76784, which merges unionai-examples #319-323 — the GitHub, Slack,
Jira, ClickUp, and Linear webhook examples.
Verified against the merged tree rather than assumed: all 24 code references
from these pages resolve to a real file and a real fragment marker on examples
origin/main, both Hugo variants build, check-links passes, and no page renders
a "File not found" or "Fragment not found" banner.
Built with `make variant` rather than `make dist` on purpose — dist runs
update-api-docs, which regenerates the whole SDK reference and leaves ~380
unrelated modified files in the tree.
Signed-off-by: Niels Bantilan <niels.bantilan@gmail.com>
GHA build & deploy previewBuilt by
Updated automatically on every push. |
cosmicbboy
added a commit
to flyteorg/flyte-sdk
that referenced
this pull request
Oct 2, 2026
…send (#1645) Found while triaging GitHub Copilot's review of unionai/unionai-docs#1673, which flagged the ClickUp header as its three high-severity findings. They're one bug, and it belongs here rather than in the docs. Linear has the same bug; Copilot did not catch that one. ## The bug `ClickUpProvider` looked for `X-Clickup-Signature`; ClickUp signs with **`X-Signature`**. `LinearProvider` looked for `X-Linear-Signature`; Linear signs with **`Linear-Signature`**. Neither header is present on a real delivery, so `verify` hit its `if not signature` guard, returned `False`, and `_app.py` raised **401 before `parse` ever ran**. With `require_signature=True` — the default — both integrations rejected every genuine webhook. Not a degraded path: nothing got through. Verified against the vendor docs ([ClickUp](https://developer.clickup.com/docs/webhooksignature), [Linear](https://linear.app/developers/webhooks)). I checked the other three providers too: GitHub `X-Hub-Signature-256` and Slack `X-Slack-Signature` are correct and untouched, and Jira's `X-Webhook-Token` is the plugin's own shared-token stand-in because Jira Cloud doesn't sign webhooks at all. ## Why CI was green Each plugin's `SAMPLE_DELIVERY` signs with the same wrong header its own `verify` reads, so `assert_provider_conforms` verified the sample against itself and passed. The round trip is self-consistent no matter what the header is called — it can never catch this class of bug. The per-plugin `_parse` helpers also built signature headers that `parse` ignores entirely. They tested nothing and propagated the wrong name into two more files. ## Changes - **Providers** — correct header in the lookup and in the docstring that generates the API reference (`clickup/_provider.py`, `linear/_provider.py`). - **Sample deliveries** — `_sample_headers` emits the real header, so `SAMPLE_DELIVERY` now mirrors an actual delivery. - **New test per provider** — asserts the literal wire header verifies and the old name does not. This is the one thing the round trip can't check. Confirmed it fails against the pre-fix code. - **`_parse` helpers** — stop fabricating headers `parse` doesn't read. - **Shared conformance helper** — `_CREDENTIAL_HEADERS` gates the hostile-credential check *by header name* and `continue`s on anything unlisted, so renaming a header silently switched that check off instead of failing. Updated the names and made a no-match assert, so it can't degrade to a no-op the same way again. - **Docs** — `plugins/clickup/README.md`, `plugins/linear/README.md`, `plugins/README-saas-integrations.md`. ## Verification - All five SaaS plugin suites pass: clickup 6, linear 6, github 45, slack 24, jira 6. - Core webhook tests pass: 103 (`tests/flyte/extras/webhooks`, `tests/flyte/app/extras/test_webhook_app.py`). - Re-introduced the ClickUp bug on both files as a control: the new wire-contract test fails, and so does conformance via the new `_CREDENTIAL_HEADERS` guard. Two independent nets now catch it. - `ruff check`, `ruff format --check`, and the pre-commit `fmt`/`mypy`/`ty` hooks pass. No dependency or `pyproject.toml` changes, so the `uv.lock` gate is untouched. ## Docs follow-up unionai/unionai-docs#1673 should regenerate the `content/api-reference/.../clickup/` pages after this merges (they render the docstrings above) and hand-edit `content/integrations/saas-integrations/clickup.md`. The Linear pages in that PR need the same correction, which the review didn't flag. The remaining low-severity comments there are docs-wording only and imply no further SDK change. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>
flyte-sdk #1645 fixed both providers: ClickUp signs with `X-Signature`, not `X-Clickup-Signature`, and Linear with `Linear-Signature`, not `X-Linear-Signature`. Before 2.10.7 `verify` looked for headers no real delivery carries, so with the default `require_signature=True` both integrations returned 401 to every genuine webhook. Two kinds of change here. Regenerated all five API references at 2.10.7. The only substantive diff is the two corrected `verify` docstrings; the rest is the version stamp. All five move together so the advisory freshness check stays clean -- confirmed committed=2.10.7 latest=2.10.7 for each. Corrected the header by hand in the four places prose names it: both landing tables, plus the ClickUp and Linear pages. On those two pages the fix is not a find-and-replace. Each now says why the right name looks wrong, because a reader who distrusts it will "fix" it back and lose every delivery: ClickUp's is `X-Signature` and not the `X-Clickup-Signature` it looks like it should be; Linear's has no `X-` prefix at all. The issue raised was about ClickUp, but #1645 fixed Linear identically and its own PR body flags that these docs needed the same correction. Both are done rather than leaving Linear quietly wrong. GitHub, Slack, and Jira prose is untouched and was already right: `X-Hub-Signature-256`, `X-Slack-Signature`, and Jira's `X-Webhook-Token` shared-token stand-in. Built with `make variant`, not `make dist`, so the tree carries no regenerated-SDK noise. Submodule pointers untouched -- the matching examples update is unionai-examples #324, which this PR does not depend on. Signed-off-by: Niels Bantilan <niels.bantilan@gmail.com>
Deliberate pointer bump, 7b76784..17d01d5, picking up unionai-examples #324: the ClickUp and Linear examples now pin 2.10.7 and their replay tasks assert the signature header a real delivery carries. The embedded `replay` fragments on those two pages pick that up. The more important change is prose. The landing page claimed `SAMPLE_DELIVERY` is "how `verify` and `parse` are checked against something the product actually sent rather than against each other." The ClickUp and Linear bug disproves that as written, and it is the exact misconception that let the bug ship, so leaving it would be worse than the original omission. What is true: the *body* is real, so field extraction is checked against reality. The *headers* are fabricated by the plugin, so for anything whose name the plugin chooses -- the signature header above all -- the sample agrees with `verify` whatever that name is. Both providers shipped reading a header no real delivery carries, with conformance green and every genuine webhook getting a 401. The page now says that. Each product page gets a note on why its replay asserts the header *name*: it is the one check a round trip cannot make, and worth copying for any provider a reader adds. Verified after the bump: all 24 code references resolve against the new tip, both variants build, every check passes, and no page renders a not-found banner. Known and deliberately not fixed here: the same overstatement survives in one docstring line in the merged github_tasks.py example, which this page renders. It is imprecise rather than false -- GitHub's header was always correct -- and not worth a third examples PR plus another pointer bump on its own. Signed-off-by: Niels Bantilan <niels.bantilan@gmail.com>
Renames the section from "SaaS integrations" to "SDLC integrations" and moves it directly below Agent frameworks in both nav trees. The rename goes all the way down rather than stopping at the title, so nothing is left reading as a leftover: the URL (`integrations/sdlc-integrations/`), the api-reference path, the registry `name`/`output_folder` keys, and the five linkmap files. No redirects are owed -- the old path never reached main, which `detect_moved_pages` and `check-deleted-pages` both confirm rather than my assuming it. Framing follows the name. The section intro now says these let something that happened in "one of your team's own tools" start a run, rather than "another product", which pairs it with the Software development lifecycle user guide. "SaaS" survives in the two places it is still the precise word: that these receive calls *from* SaaS products, and upstream's own `examples/external_saas_integrations` in the generated docstrings, which is not ours to edit. Two separate ordering defects, both now fixed: - The category list had this at item 11, at the end, while its prose section sat third. Moved to item 3, right after Agentic AI, and renumbered. The list and the section order now agree. - The sidebar was the real problem. Every other integration carries `weight: 1`, so a `weight: 2` sorted this section *last*, not second. The existing convention is "agents pinned first, everything else alphabetical"; this extends it to a two-item pinned group -- agents 1, sdlc-integrations 2, the other 21 bumped to 3. That is the 21-file diff here, and it preserves their relative (alphabetical) order exactly. The api-reference side needed no weight changes: generated plugin pages carry no weight at all, so they already sorted after the two weighted entries. Verified in the built HTML rather than inferred from frontmatter: both nav trees render Agent frameworks then SDLC integrations. Also zero `saas-integrations` references left anywhere tracked, no stale output under the old path, and no code-shortcode error banners site-wide. Signed-off-by: Niels Bantilan <niels.bantilan@gmail.com>
cosmicbboy
changed the title
Spells the section out, matching the user-guide section of the same name, so the two read as one story rather than one acronym and one phrase. Carried all the way down again -- URL (`integrations/software-development-lifecycle/`), api-reference path, and the regenerated linkmaps, which held the old URLs and would otherwise have pointed the inline-code linker at 404s. No redirects owed: the old path never reached main, confirmed by detect_moved_pages and check-deleted-pages rather than assumed. Two deliberate exceptions to spelling it out: The registry `name` keys stay `sdlc-<product>`. `name` is the linkmap filename and appears in no URL, so spelling the section out would give every linkmap a 40-character prefix for no reader-visible gain. The comment block now says so, since the next person to read it will otherwise wonder why it disagrees with output_folder. Prose that referred to the section by name now says "These integrations" rather than repeating the full phrase immediately under a heading that already says it. Verified in the built HTML in both variants, both nav trees: Agent frameworks -> Software development lifecycle. No stale output under either previous path, no code-shortcode error banners, and every check passes. Signed-off-by: Niels Bantilan <niels.bantilan@gmail.com>
cosmicbboy
changed the title
Gives the integrations section its own name, so it no longer collides with the Software development lifecycle user guide. The pairing stays legible -- tools on one side, the lifecycle they serve on the other -- without two nav entries, two breadcrumbs, and two search results reading identically. Renamed through the URL (`integrations/software-development-tools/`), the api-reference path, and the linkmaps, which still held the previous URLs and would otherwise have pointed the inline-code linker at 404s. Still no redirects owed: no earlier path ever reached main, confirmed by detect_moved_pages and check-deleted-pages. Registry `name` keys move sdlc-<product> -> devtools-<product>. They stay abbreviated for the reason the comment already gives -- `name` is the linkmap filename and appears in no URL -- but `sdlc` would now name something this section is not. Fixed two sentences while here. "This is the richest of the [Software development lifecycle]" and "Slack is the broadest of the [Software development lifecycle] in both directions" were left as broken noun phrases by an earlier rename, which swapped a plural category name into a slot that needed one. Both now read "of these integrations", which does not break again on the next rename. Dropped the disambiguating wording added when the two sections shared a name: links from here to the user guide are plain again. Verified in the built HTML, both variants, both nav trees: Agent frameworks -> Software development tools. No stale output under any previous path, no code-shortcode error banners, and every check passes. Signed-off-by: Niels Bantilan <niels.bantilan@gmail.com>
cosmicbboy
changed the title
Rewrite the landing page and the five product pages for task-first reference style: - Lead with a quick start; move the API-wrapper rationale to a short "Calling the product's API" section. - State version requirements (ClickUp, Linear: 2.10.7+) instead of recounting the signature-header bug. - Drop editorial asides and sentence-length notice titles; state gotchas plainly. - Fix the Jira sentence missing its `require_signature=True` reference. - Correct the no-scope claim: events without a scope are skipped only when a `scopes` allowlist is set (flyte/extras/webhooks/_app.py). - Tighten the API-reference group landing page and the integrations index summary to match. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com> Signed-off-by: Peeter Piegaze <1153481+ppiegaze@users.noreply.github.com>
Pick up unionai/unionai-examples#325, which tightens the comments in the software development tools webhook examples embedded on these pages. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com> Signed-off-by: Peeter Piegaze <1153481+ppiegaze@users.noreply.github.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Documents the five webhook provider plugins from flyte-sdk —
flyteplugins-{github,slack,linear,clickup,jira}— as an integrations guide and as API reference.Each plugin adds one
Providerto the receiver inflyte.extras.webhooks, which ships with Flyte and is already documented with the SDK. An app built on it verifies deliveries from these products, parses them into a commonWebhookEvent, and launches one run per event.What's here
Integrations guide at
content/integrations/software-development-tools/:_index.md: quick start, the event model,run_oncededuplication,scopes, offline testing withSAMPLE_DELIVERY, and deployment.content/integrations/_index.md.API reference at
content/api-reference/integrations/software-development-tools/:api-packages.tomland generated at 2.10.7, with a hand-written group landing page, following theagents/pattern.linkmap/devtools-*-linkmap.json. The registrynamekeys use the shortdevtools-prefix because they name the linkmap files and appear in no URL.extrason any entry:review_prandmint_installation_tokenimport PyGithub and PyJWT lazily, so the parser imports each package without them.The generator documents classes and functions, not modules, so each package's
eventsconstants aren't in the generated reference. They're listed on the product pages.Things worth reviewing
require_signature=Falsein production.scopesis set, events with no scope are acknowledged but not dispatched (flyte/extras/webhooks/_app.py). The landing page and the Linear page explain where each provider reads the scope from.Sidebar order
The section sits directly below Agent frameworks in both the integrations and API-reference sidebars. Other integration pages had
weight: 1, so this PR changes 21 of them toweight: 3; their relative alphabetical order is unchanged. That's the 21 one-line changes in the diff. New integration pages should useweight: 3to sort after these two sections.Examples
The pages embed examples from
unionai-examples/v2/integrations/flyte-plugins/{github,slack,jira,linear,clickup}/. This PR bumps theunionai-examplespointer tob663d54, which includes unionai/unionai-examples#325 (a style pass on those examples' comments).Verification
make check-links,check-icon-names,check-api-names,check-subpage-cards,check-search-labels, andcheck-heading-shortcodespass.HMACis added to the project dictionary.Follow-up
A stacked PR adds the Software development lifecycle user-guide section and links from these pages to it.
🤖 Generated with Claude Code