Sources d'extensions

Les sources d'extensions permettent à vos développeurs de pousser des extensions vers une infrastructure qu'ils contrôlent déjà — un dépôt Git ou un registre OCI — et que votre installation Scrydon les récupère automatiquement selon un calendrier. Aucun trafic entrant, aucun téléversement manuel à chaque version.

Fonctionnement

Votre installation Scrydon exécute un réconciliateur qui interroge chaque source enregistrée selon un intervalle configurable (5 minutes par défaut, minimum 30 secondes). À chaque cycle, il :

1. Récupère le fichier catalogue scrydon.yaml depuis votre source.
2. Le compare aux versions du catalogue déjà synchronisées.
3. Pour chaque entrée nouvelle ou modifiée : récupère l'artefact, vérifie sa signature et le publie dans le catalogue de l'organisation.
4. Enregistre le résultat du catalogue et les compteurs d'entrées ordinaires dans l'historique des exécutions de la source. La réponse d'une synchronisation manuelle et le journal du réconciliateur contiennent aussi le résumé borné de l'ontologie par environnement décrit ci-dessous.

Lorsqu'un administrateur de l'organisation clique sur Synchroniser dans Paramètres → Plateforme → Extensions → Sources, Scrydon installe également le contenu à l'échelle de l'organisation (code, ontologies et serveurs MCP) des extensions synchronisées avec succès, en utilisant la même autorisation et le même pipeline d'installation que Ajouter une extension. Elles apparaissent ensuite sous Installées sans étape d'ajout séparée. Les entrées de catalogue inchangées sont incluses, de sorte que la synchronisation peut terminer des installations manquantes ou ayant précédemment échoué. Les erreurs d'installation sont affichées séparément des compteurs du catalogue ; un échec n'empêche pas les autres extensions de s'installer.

Les identifiants et l'activation dans les espaces de travail restent des étapes de configuration distinctes. Les workflows, les process flows, les sources de données et les notebooks conservent leur configuration propre à chaque espace de travail. La synchronisation planifiée en arrière-plan actualise le catalogue et suit la politique de mise à jour additive existante ; elle ne reçoit pas l'autorisation d'installation de l'administrateur interactif. Lancez Synchroniser pour installer le contenu à l'échelle de l'organisation nouvellement découvert.

Le réconciliateur fonctionne en mode pull uniquement. Votre pipeline CI n'a jamais besoin d'un accès entrant vers votre cluster Scrydon.

Réconciliation de l'ontologie entre environnements

L'état de l'ontologie appartient à un environnement d'espace de travail ; une synchronisation de source n'envoie donc jamais une requête d'ontologie unique au niveau de l'organisation. Le réconciliateur énumère les vrais environnements d'espace de travail de l'organisation dans un ordre stable et applique chaque extension d'ontologie éligible une fois par environnement, avec au plus huit applications simultanées. Les sources de données de référence statiques restent à l'échelle de l'organisation et sont appliquées une fois par extension, pas une fois par environnement.

Pour les extensions déjà installées dans un environnement, les mises à jour automatiques de l'ontologie sont additives. Un environnement où l'extension n'est pas installée est compté comme skipped avec la raison not_installed ; la synchronisation ne l'installe pas implicitement. Le réconciliateur revisite toutes les cibles même lorsque l'entrée source elle-même n'a pas changé, de sorte qu'une nouvelle tentative après une réussite partielle peut converger sans republier l'artefact.

L'échec d'un environnement n'annule pas les tentatives sur les autres environnements et ne les empêche pas. La réponse de l'API Synchroniser maintenant sous-jacente fournit targetAttempts, le nombre de cibles appliquées, ignorées et échouées, ainsi qu'un digest couvrant tous les échecs et au plus les 16 premiers résumés bornés de cible/erreur. Le toast des Paramètres n'affiche actuellement que les compteurs d'entrées ; les tuples des cibles échouées et les compteurs agrégés sont également écrits dans le journal structuré de l'exécution en cours. La ligne stockée dans l'historique des exécutions conserve le statut, l'erreur et les compteurs d'entrées habituels ; elle ne persiste ni le résumé complet des cibles ni le corps du manifeste.

Si l'organisation ne possède aucun environnement d'espace de travail, l'application automatique de l'ontologie signale no_workspace_environments et n'effectue aucun appel d'ontologie. La réconciliation du catalogue et les types de contenu indépendants peuvent tout de même aboutir ; vérifiez donc toujours les compteurs d'ontologie dans le résultat de Synchroniser maintenant au lieu d'interpréter une exécution du catalogue par ailleurs réussie comme la preuve que toutes les cibles d'ontologie ont été appliquées.

Chaque cible réussie enregistre l'identifiant réel de la ligne de catalogue, l'identifiant de la source, la référence immuable de l'entrée source et l'instantané complet du manifeste normalisé. Ces champs permettent à la page Paramètres → Plateforme → Extensions de détecter des environnements manquants ou divergents sans déduire l'état à partir des horodatages ou des identifiants de révision propres aux environnements.

Le catalogue source fait autorité

Le fichier catalogue scrydon.yaml est la source de vérité pour les extensions qui apparaissent dans le catalogue de votre organisation. Il fait autorité dans les deux sens :

• Listée mais retirée → restaurée. Si un administrateur retire du catalogue, depuis l'interface, une extension gérée par une source, la prochaine synchronisation la restaure tant qu'elle est encore listée — de la même façon que re-téléverser manuellement une extension retirée.
• Non listée → retirée. Lorsque vous supprimez une entrée de scrydon.yaml, la prochaine synchronisation réussie retire les lignes de catalogue de cette extension. Elle disparaît du catalogue et ne peut plus être installée. Rajoutez l'entrée et la synchronisation suivante la restaure.

Pour supprimer définitivement une extension gérée par une source :

• supprimez son entrée du scrydon.yaml de la source, ou
• désactivez (ou supprimez) la source elle-même.

Trois choses que ce balayage ne fait délibérément pas :

• Il ne touche jamais aux anciennes versions d'une extension qui est toujours listée. Votre catalogue conserve l'historique des versions ; seules les extensions que le fichier ne nomme plus du tout sont retirées.
• Il ne s'exécute jamais sur un catalogue vide. Un scrydon.yaml qui ne contient aucune extension après analyse est laissé tel quel, de sorte qu'un fichier tronqué ou mal modifié ne peut pas vider votre catalogue lors d'une synchronisation sans surveillance. Pour vider délibérément une source, désactivez-la ou retirez ses extensions manuellement.
• Il ne touche jamais aux extensions téléversées manuellement ni aux extensions d'autres sources.

Retirer une extension modifie sa visibilité dans le catalogue, ce n'est pas une désinstallation : le contenu déjà installé dans les espaces de travail continue de fonctionner. Chaque synchronisation indique, dans l'historique des exécutions de la source, combien d'extensions elle a retirées ainsi que combien elle en a installées.

Le retrait manuel reste utile pour les extensions téléversées manuellement (aucune source ne les gère, elles restent donc retirées) et comme masquage temporaire des extensions gérées par une source entre deux synchronisations.

Choisir un type de source

Vous pouvez enregistrer plusieurs sources de chaque type par organisation.

Le fichier catalogue scrydon.yaml

Chaque source est décrite par un unique fichier scrydon.yaml situé à un chemin configurable dans votre dépôt ou registre. Ce fichier est la source de vérité pour les extensions à installer et leur version.

apiVersion: scrydon.io/v1
kind: ExtensionCatalog
extensions:
  - id: example.sample
    version: 1.0.0
    artifact:
      kind: git-tar
      ref: main
      path: extensions/sample
    signature:
      kind: none

  - id: example.fraud
    version: 1.2.0
    artifact:
      kind: oci
      ref: ghcr.io/example/scrydon-fraud@sha256:abc123def456...
    signature:
      kind: cosign-keyless
      certificateIdentityRegexp: "https://github.com/example/.*"
      certificateOidcIssuer: "https://token.actions.githubusercontent.com"

Champs du catalogue d'extensions

Publication depuis la CI

Organisation d'une source Git

Pour une source Git, votre dépôt contient le catalogue scrydon.yaml aux côtés de vos répertoires d'extensions. Le réconciliateur empaquette à la volée le sous-répertoire déclaré, à la référence configurée, dans un fichier .scrydon-extension.tar.gz.

Organisation minimale :

my-extensions/
├── scrydon.yaml          # Extension catalog
├── extensions/
│   └── fraud/            # Extension directory — each has an extension.json
│       ├── extension.json
│       └── ontology/
│           └── manifest.json
└── .github/
    └── workflows/
        └── validate.yml  # Validates scrydon.yaml on every PR

Validez scrydon.yaml sur les pull requests pour détecter les erreurs de catalogue avant qu'elles n'atteignent votre installation Scrydon :

# .github/workflows/validate.yml
name: validate-catalog
on:
  pull_request:
    paths: ['scrydon.yaml', 'extensions/**']
jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: oven-sh/setup-bun@v2
      - name: Validate catalog schema
        run: |
          bunx @scrydon/sdk-authoring sources validate scrydon.yaml

Organisation d'une source OCI

Pour une source OCI, votre pipeline CI construit un fichier .scrydon-extension.tar.gz pour chaque extension, le pousse en tant qu'artefact OCI, le signe avec cosign, et met à jour le catalogue scrydon.yaml (également poussé en tant qu'artefact OCI).

- uses: sigstore/cosign-installer@v3
- uses: oras-project/setup-oras@v1

bunx @scrydon/sdk-authoring extension build extensions/fraud --outDir dist/fraud
echo "ARCHIVE=$(ls dist/fraud/*.scrydon-extension.tar.gz)" >> "$GITHUB_ENV"

oras push ghcr.io/${{ github.repository_owner }}/scrydon-fraud:${{ github.ref_name }} \
  --artifact-type application/vnd.scrydon.extension.v1.tar.gzip \
  "$ARCHIVE:application/vnd.scrydon.extension.v1.tar.gzip"

COSIGN_EXPERIMENTAL=1 cosign sign --yes \
  ghcr.io/${{ github.repository_owner }}/scrydon-fraud:${{ github.ref_name }}

DIGEST=$(oras manifest fetch --output - \
  ghcr.io/${{ github.repository_owner }}/scrydon-fraud:${{ github.ref_name }} \
  | jq -r '.config.digest // .digest')
sed -i "s|REPLACE_WITH_DIGEST|$DIGEST|" catalog/scrydon.yaml

oras push ghcr.io/${{ github.repository_owner }}/scrydon-catalog:catalog \
  --artifact-type application/vnd.scrydon.catalog.v1+yaml \
  catalog/scrydon.yaml:application/vnd.scrydon.catalog.v1+yaml

Des exemples complets et fonctionnels se trouvent dans le répertoire examples/extension-sources/ du dépôt du SDK Scrydon.

Enregistrer une source via l'interface Paramètres

Authentification d'une source privée

Les dépôts Git privés et les registres OCI privés nécessitent un identifiant. Collez-le directement dans le champ Identifiant d'accès de la source — Scrydon l'enregistre pour vous comme un secret d'organisation chiffré et établit la référence automatiquement. Vous n'avez jamais à gérer un secret séparé manuellement.

Livraison d'extensions personnalisées

Une extension peut inclure une entrée de contenu extension dans son extension.json. Lors de l'installation d'une telle extension, la plateforme enregistre l'extension personnalisée aux côtés de tout autre type de contenu (ontologie, process flow, etc.) — aucune étape de téléversement séparée n'est nécessaire.

La synchronisation place uniquement les extensions dans le catalogue de votre organisation — l'installation est une seconde étape explicite. Le catalogue Paramètres → Plateforme → Extensions → Ajouter une extension est l'endroit où les extensions personnalisées sont découvertes et installées pour la première fois. La ligne d'une extension dans l'onglet Installées (et l'onglet Version & sécurité de sa fiche) permet de suivre l'état d'installation pour tous les types de contenu et d'appliquer les mises à jour.

Dans le catalogue Ajouter une extension, une extension personnalisée synchronisée est une ligne qui nomme son extension (depuis l'extension <extension>), listée parmi les fournisseurs auxquels elle appartient — et Filtrer → Source → Depuis vos extensions n'affiche que celles-ci :

• Pas encore installée — affiche Connecter lorsque la première étape après l'installation est un identifiant, et Installer sinon ; l'une comme l'autre installe et active l'extension immédiatement, et Connecter enchaîne directement sur son étape de connexion.
• Déjà installée et à jour — est la ligne du fournisseur lui-même, repliée sous la ligne N installées de son groupe, avec Gérer qui ouvre le panneau du fournisseur.
• Mise à jour disponible — n'est pas proposée dans Ajouter une extension. La ligne du fournisseur dans l'onglet Installées l'affiche dans la colonne version (1.3.0 → 1.4.0), et la mise à jour s'examine et s'applique dans la fiche de l'extension sous Version & sécurité. Voir Gestion des versions d'extensions.

L'installation d'une extension entière (y compris ses types de contenu autres qu'extension, tels que l'ontologie, les workflows et les sources de données) se fait depuis le groupe Solutions et contenu du catalogue Ajouter une extension.

Connecter ou installer une extension depuis le catalogue Ajouter une extension l'active immédiatement — l'action explicite de l'administrateur constitue la révision. La politique de signature contrôle les flux non interactifs :

Limites de taille pour les artefacts d'extension : 8 Mo par archive.tar.gz, dans une archive d'extension de 16 Mo compressés au maximum. Les deux sont appliquées par le même pipeline quelle que soit la façon dont l'extension arrive — synchronisation d'une source ou téléversement ponctuel — il n'existe donc pas de porte plus large ; un artefact de plus de 8 Mo doit être réduit. Voir le guide de création d'extensions pour la structure complète des sous-répertoires et la déclaration extension.json.

Politiques de signature

Chaque artefact d'extension doit passer la vérification de signature avant d'être installé. La politique de signature est définie par source lors de l'enregistrement.

Les nouvelles sources utilisent cosign-keyless par défaut. Les déploiements réglementés peuvent définir la valeur Helm auth.requireSignedExtensionSources: true ; les politiques comportant une branche acceptant du contenu non signé sont alors refusées lors de la création, de la mise à jour, du test de connexion, de la réconciliation et de l'activation dans un espace de travail. Le contenu non signé déjà présent dans le catalogue ne peut pas être activé tant que ce paramètre est actif.

cosign-keyless (recommandé)

signature:
  kind: cosign-keyless
  certificateIdentityRegexp: "https://github.com/acme/scrydon-extensions/.*"
  certificateOidcIssuer: "https://token.actions.githubusercontent.com"

Le réconciliateur appelle cosign verify avec ces contraintes. L'émetteur OIDC et l'identité du certificat doivent correspondre exactement — une extension signée dans un dépôt différent ou par un système CI différent échouera à la vérification.

Pour que cela fonctionne, votre workflow de publication doit demander la permission id-token: write et utiliser sigstore/cosign-installer@v3.

cosign-key

signature:
  kind: cosign-key
  publicKey: |
    -----BEGIN PUBLIC KEY-----
    MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAE...
    -----END PUBLIC KEY-----

Générez une paire de clés avec cosign generate-key-pair et collez la clé publique ci-dessus. Conservez la clé privée dans un secret CI (COSIGN_PRIVATE_KEY) et signez avec cosign sign --key env://COSIGN_PRIVATE_KEY.

unsigned-allowed

À utiliser uniquement pour le développement local ou les environnements de laboratoire isolés où l'exécution d'une infrastructure de signature est impraticable. Dans scrydon.yaml, les entrées sous une source unsigned-allowed utilisent signature: { kind: none }.

Si auth.requireSignedExtensionSources est activé, unsigned-allowed reste indisponible même lors d'une action explicite d'un administrateur. Configurez cosign-keyless, cosign-key ou une autre politique dont chaque branche impose la vérification de signature.

Dépannage

verify_failed

La vérification de signature a échoué pour un ou plusieurs artefacts d'extension.

• Vérifiez que votre workflow de publication a la permission id-token: write (pour le mode sans clé).
• Confirmez que certificateIdentityRegexp correspond à l'URL d'exécution GitHub Actions de votre dépôt (par ex. https://github.com/acme/scrydon-extensions/.*).
• Confirmez que certificateOidcIssuer correspond au fournisseur OIDC utilisé par votre CI (https://token.actions.githubusercontent.com pour GitHub Actions).
• Pour cosign-key : vérifiez que la clé publique dans la configuration de la source correspond à la clé privée utilisée pour signer l'artefact.
• Vérifiez que l'extension a été signée après avoir été poussée dans le registre — signer un tag ou un digest différent de celui référencé dans scrydon.yaml échouera.

fetch_failed

Le réconciliateur n'a pas pu atteindre votre source.

• Pour les sources Git : vérifiez que l'URL est une URL de clonage HTTPS et que les identifiants (PAT ou clé de déploiement) ont la portée read sur le dépôt.
• Pour les sources OCI : vérifiez que la référence de registre est correcte et que les identifiants de tirage ont un accès en lecture au dépôt.
• Vérifiez que la source est accessible depuis le réseau de votre cluster Scrydon. Le réconciliateur effectue des requêtes HTTPS sortantes — assurez-vous que le trafic sortant n'est pas bloqué.
• Cliquez sur Tester la connexion dans les Paramètres pour obtenir une erreur plus détaillée.

parse_failed

scrydon.yaml a échoué à la validation du schéma.

• Exécutez le validateur localement : bunx @scrydon/sdk-authoring sources validate scrydon.yaml
• Causes courantes : clés inconnues (fautes de frappe), champs requis manquants, format d'identifiant d'extension invalide (doit être en minuscules avec des points, par ex. acme.fraud), semver invalide, ref d'artefact manquant pour les entrées OCI.
• Confirmez que le fichier est un YAML valide avant de vérifier le schéma.

install_failed

L'extension a été récupérée et vérifiée mais son installation a échoué.

• L'archive de l'extension elle-même est peut-être malformée. Testez-la localement : bunx @scrydon/sdk-authoring extension test extensions/fraud
• Vérifiez le détail de l'erreur dans l'historique des exécutions sous Paramètres > Plateforme > Extensions > Sources — cliquez sur une ligne de source (ou son action Voir l'historique) pour ouvrir le panneau d'historique — pour l'erreur de validation extension.json spécifique.
• Confirmez que extension.json package.id correspond au schéma en minuscules avec points et que installOrder correspond aux types dans contents.

no_workspace_environments

L'organisation ne possède aucun environnement d'espace de travail pouvant recevoir le contenu d'ontologie. Aucune requête d'ontologie n'a été envoyée. Créez l'environnement d'espace de travail prévu, puis relancez Synchroniser maintenant. Le hook de création d'environnement installe l'ontologie knowledge-base intégrée dans cet environnement ; les extensions gérées par une source convergent toujours lors de la synchronisation de source suivante.

Certaines cibles d'ontologie ont échoué ou ont été ignorées

• Vérifiez ontologyAutoApply dans la réponse de l'API Synchroniser maintenant sous-jacente. Comparez targetAttempts aux nombres de cibles appliquées, ignorées et échouées.
• not_installed est un saut intentionnel : la réconciliation automatique met à jour une extension installée, mais n'inscrit pas un nouvel environnement à cette extension.
• Pour les échecs, utilisez le tuple d'espace de travail et d'environnement renvoyé ou journalisé ainsi que le texte d'erreur borné. Le digest d'échec couvre l'ensemble complet lorsque plus de 16 résumés existent.
• Corrigez la cause propre à la cible puis relancez Synchroniser maintenant. Les cibles réussies sont idempotentes et les entrées source inchangées sont délibérément revisitées.
• Ne copiez pas le corps d'un manifeste dans les tickets ou les journaux. Utilisez les champs de provenance du catalogue/de la source et les digests pour corréler l'artefact.

La source indique « géré par le chart » et est en lecture seule

Cette source a été initialisée via extensionSources: dans vos valeurs Helm. Modifiez les valeurs du chart pour la changer — ne créez pas une source dupliquée gérée par l'interface avec le même nom.

La synchronisation s'arrête après des échecs répétés

Après trois exécutions consécutives échouées, le réconciliateur augmente l'intervalle au double de celui configuré (plafonné à une heure). Corrigez l'erreur sous-jacente — le recul se réinitialise automatiquement lors de la prochaine synchronisation réussie. Cliquer sur Synchroniser maintenant dans l'interface réinitialise le compteur immédiatement.

Une extension retirée est revenue / une extension est absente du catalogue

Les extensions gérées par une source suivent le catalogue de la source : une extension retirée qui est encore listée dans scrydon.yaml est restaurée lors de la prochaine synchronisation, et une extension qui n'est plus listée est retirée (voir Le catalogue source fait autorité). Si une extension attendue est absente, vérifiez qu'elle est listée dans le scrydon.yaml de la source, que la dernière exécution dans l'historique de la source a réussi, et que le toast Synchroniser maintenant l'indique comme installée.

La liste des extensions installées est incomplète après une synchronisation réussie

La liste Installées lit l'état d'installation auprès des services qui possèdent chaque type de contenu. Si l'un de ces services est indisponible, la liste affiche un avertissement indiquant qu'elle est incomplète. Rétablissez le service concerné, puis sélectionnez Réessayer. Vous n'avez pas besoin d'ajouter ou de réinstaller une extension qui a déjà été installée avec succès.

Progression de la synchronisation

La synchronisation manuelle affiche la récupération du catalogue, le nombre d'extensions vérifiées et le nombre d'installations avec le nom de l'extension. Les vérifications et installations indépendantes s'exécutent jusqu'à trois à la fois, et les sources Git réutilisent leur extraction pendant chaque exécution. Les versions actuelles du code et de l'ontologie sont signalées comme déjà installées ; les versions plus anciennes sont mises à jour via le flux d'installation normal.

Inspecter les extensions installées

La liste Installées regroupe les extensions de votre organisation sous son nom actuel et les extensions tierces sous Autres fournisseurs. Les versions des fournisseurs reflètent le manifeste du fournisseur en cours d'exécution ; les versions des extensions issues d'une source reflètent la version installée.

Ouvrez l'onglet Fournit d'une extension pour voir les badges de capacités directement dans chaque ligne. Sélectionnez un badge pour inspecter ses membres, y compris les types d'ontologie et les sources de données. Les liaisons d'ontologie affichent la table source et le type cible au lieu d'espaces réservés numérotés. L'onglet Connexions affiche, pour chaque identifiant, le compte, le statut, l'environnement et les produits couverts ; les actions de connexion sont disponibles depuis le menu de sa ligne.

Une installation échoue avec marketplace_content_invalid

L'une des entrées de contenu de l'extension est présente dans la ligne du catalogue mais n'a pas pu être décodée ; il n'y a donc rien à installer pour elle. Le message indique quelle vérification a échoué — par exemple marketplace_content_invalid:invalid_content_entry — et les journaux de votre opérateur contiennent l'erreur de schéma sous-jacente (par exemple manifestVersion: Invalid input: expected 1).

La cause habituelle est un contenu rédigé selon un contrat de manifeste plus récent que celui accepté par l'installation. Les autres entrées de la même extension ne sont pas affectées et restent installables ; seule l'entrée qui n'a pas pu être décodée est refusée.

• Validez l'extension localement : bunx @scrydon/sdk-authoring extension test extensions/<name>
• Comparez la manifestVersion du manifeste du contenu en échec à la version du SDK exécutée par votre installation.

Champs d'identité des extensions

Les requêtes de catalogue et d'installation d'extensions utilisent extensionId et extensionVersion. La provenance de l'ontologie utilise extensionOrigin. Les enregistrements MCP et de version de code distinguent leur extensionId de code/fournisseur de leur catalogExtensionId englobant.

Lorsque vous reconstruisez des workflows rédigés, le bloc Create Process Instance prend extensionId. Mettez à jour les définitions plus anciennes pour utiliser ce champ avant de les publier avec le SDK actuel. Les workflows installés sont migrés avec la plateforme ; les archives de source publiées restent immuables et nécessitent une nouvelle version pour modifier leur contenu.