| name | ory-contribute-integration |
| description | Author a new Ory Network integration as a contribution to the public ory/integrates repository. Use when the user wants to contribute an integration back to Ory, add an entry to the Ory integrations registry/catalog, open a PR against ory/integrates, or publish a reusable integration for others — phrases like "contribute an Ory integration", "add my integration to ory/integrates", "submit a webhook integration to Ory", "get my integration into the registry". For wiring an integration into your own app instead, use ory-build-integration. |
Contribute an Integration to ory/integrates
You are helping the user author a new integration and contribute it back to the
public ory/integrates repository ("Sample code and reference configuration for
integrating Ory Network with third-party products"). The deliverable is a pull
request against github.com/ory/integrates.
This skill carries the workflow. The template files live in the repo itself —
fetch them from github.com/ory/integrates (branch main) rather than
reproducing them, so they never drift.
Precondition: ory/integrates must be reachable (it is a public repo). If
gh repo view ory/integrates or a fetch of a template file fails, tell the
user the repo is unreachable and stop — do not fabricate template contents.
Step 0 — Open the "New integration" issue first
Ory asks contributors to open a New integration issue before the PR, so scope
is confirmed and the work isn't already in flight. Remind the user to do this
(GitHub → ory/integrates → Issues → "New integration" template) and capture the
issue number for the PR.
Step 1 — Get a checkout and pick the category
The contribution workflow happens inside a checkout of the repo:
gh repo clone ory/integrates
cd integrates
(or a fork, if the user will PR from their own remote.) Then choose the
category folder the integration belongs in — it must match an existing
top-level directory (crm/, api-gateways/, identity-verification/, mfa/,
enterprise-sso/, …). List them with ls -d */ | grep -v _examples.
Step 2 — Determine the integration type
Every integration is one of three types. Infer from intent; if unclear, ask
directly.
| Signal from the user | Type | Template |
|---|
| Transform/enrich an identity at registration; gate or react to a self-service flow synchronously; call a vendor API during an Ory flow | webhook | _examples/_template-webhook/ |
| Validate Ory JWTs at a gateway; Console-only setup; no handler code | config | _examples/_template-config/ |
| React to events asynchronously; Ory Network Enterprise Live Event Stream consumer | http-event | _examples/_template-http-event/ |
Step 3 — Copy the template into the category folder
From the repo root, copy the whole template directory to
<category>/<integration-slug> (slug is lowercase, hyphenated, matches the dir
name):
cp -R _examples/_template-webhook crm/<integration-slug>
Each template ships these files (confirm with ls -R <category>/<integration-slug>):
- webhook —
README.md, ory-actions.yaml, jsonnet/identity.jsonnet,
registry.entry.yaml.example, and a runnable webhook/ (server.ts,
package.json, package-lock.json, tsconfig.json, .env.example).
- config —
README.md, ory-console-steps.md,
registry.entry.yaml.example.
- http-event —
README.md, ory-event-stream.yaml,
registry.entry.yaml.example, and a runnable webhook/ (server.ts,
idempotency.ts, package.json, package-lock.json, tsconfig.json,
.env.example).
The copied files are the source of truth — read them and fill in every
<placeholder> and <!-- comment -->.
Step 4 — Fill out the integration
- README.md — replace
<Integration Name>, set the Maintained by: line
(Ory Engineering, Community contributors, or the user's @handle), and
complete: what it does, use case, prerequisites, deploy steps, Ory Console
configuration, troubleshooting. No vendor marketing — factual wiring only.
- Code / config for the type (see per-type notes below).
- registry.entry.yaml — rename
registry.entry.yaml.example →
registry.entry.yaml and fill in every field (name, displayName,
vendor, category, type, maintainedBy, description, useCase,
coreFunctionality, oryMechanism, protocol, status; http-event also
needs subscribedEvents). The field comments in the file enumerate the
allowed enum values.
- Apache-2.0 SPDX header at the top of every source file you ship, e.g.
// SPDX-License-Identifier: Apache-2.0.
webhook specifics
ory-actions.yaml is the Ory Action hook config (a web_hook with an
X-Webhook-Secret api_key auth header). Point url at the deployed handler
and set the shared secret.jsonnet/identity.jsonnet is the request-body template — adjust to the shape
your handler expects.- The
webhook/ server must run (cd webhook && cp .env.example .env && npm install && npm start); it exposes GET /health and the POST target.
ORY_WEBHOOK_SECRET in .env must match the secret in ory-actions.yaml.
config specifics
- No code. Write a real
ory-console-steps.md: vendor-side setup, the exact Ory
Console navigation, the fields to configure, a test, and troubleshooting. A
README-only contribution with no real console steps will be rejected.
http-event specifics
ory-event-stream.yaml configures the Ory-side event target (URL with embedded
Basic Auth) and the event filter. List the consumed events under both the YAML
events: and the registry subscribedEvents:.- The
webhook/ handler authenticates with HTTP Basic Auth, dedupes by SHA-256
of the body (idempotency.ts) because delivery is at-least-once, and always
returns 200. Live event streams are an Enterprise feature — say so in the
README.
Step 5 — Regenerate the registry
From the repo root:
cd scripts && npm install && cd ..
node scripts/build-registry.js
This rewrites the top-level registry.yaml from every registry.entry.yaml.
Commit the regenerated registry.yaml along with your integration.
Step 6 — Open the PR (DCO + checklist)
Walk the CONTRIBUTING checklist before opening the PR:
git checkout -b add-<integration-slug>-integration
git add <category>/<integration-slug> registry.yaml
git commit -s -m "Add <Integration Name> integration"
git push -u origin add-<integration-slug>-integration
gh pr create --repo ory/integrates --title "Add <Integration Name> integration" \
--body "Closes #<issue-number>. <summary>"
Expect review questions about Ory Network compatibility, webhook security
(signature verification, secret handling), and README clarity.
What this skill does NOT do
- It does not wire an integration into the user's own application — use
ory-build-integration for that (no registry/DCO).
- It does not run
build-registry.js or open the PR without confirmation; it
guides, the user executes.
- It does not invent template contents — it reads the real files from
ory/integrates.
