Sources de packs

Les sources de packs permettent à vos développeurs de pousser des packs 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 précédemment installées.
3. Pour chaque entrée nouvelle ou modifiée : récupère l'artefact, vérifie sa signature et l'installe via le même pipeline qu'un téléversement manuel.
4. Enregistre le résultat — succès ou raison d'échec détaillée — dans l'historique des exécutions de la source.

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

Le catalogue source fait autorité

Le fichier catalogue scrydon.yaml est la source de vérité pour les packs présents dans le catalogue de votre organisation. Si un administrateur retire de l'interface un pack géré par une source, la prochaine synchronisation le restaure tant qu'il est encore listé dans scrydon.yaml — de la même façon que re-téléverser un pack retraité manuellement le ramène. Pour supprimer définitivement un pack géré par une source :

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

Le retrait reste utile pour les packs téléversés manuellement (aucune source ne les gère, ils restent donc retirés) et comme masquage temporaire pour les packs gérés 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 packs à installer et leur version.

apiVersion: scrydon.io/v1
kind: PackCatalog
packs:
  - id: example.sample
    version: 1.0.0
    artifact:
      kind: git-tar
      ref: main
      path: packs/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 de packs

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 de packs. Le réconciliateur emballe le sous-répertoire déclaré à la référence configurée dans un fichier .scrydon-pack.tar.gz à la volée.

Organisation minimale :

my-packs/
├── scrydon.yaml          # Catalogue de packs
├── packs/
│   └── fraud/            # Répertoire du pack — chacun contient un pack.json
│       ├── pack.json
│       └── ontology/
│           └── manifest.json
└── .github/
    └── workflows/
        └── validate.yml  # Valide scrydon.yaml à chaque 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', 'packs/**']
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-pack.tar.gz pour chaque pack, 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 pack build packs/fraud \
  --out dist/fraud-${{ github.ref_name }}.tar.gz

oras push ghcr.io/${{ github.repository_owner }}/scrydon-fraud:${{ github.ref_name }} \
  --artifact-type application/vnd.scrydon.pack.v1.tar.gzip \
  dist/fraud-${{ github.ref_name }}.tar.gz:application/vnd.scrydon.pack.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/pack-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 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'intégrations personnalisées

Un pack peut inclure une entrée de contenu integration dans son pack.json. Lors de l'installation d'un tel pack, la plateforme enregistre l'intégration personnalisée aux côtés de tout autre type de contenu (ontologie, processus, etc.) — aucune étape de téléversement séparée n'est nécessaire.

La synchronisation place uniquement les packs dans le catalogue de votre organisation — l'installation est une seconde étape explicite. Le marketplace Paramètres → Plateforme → Intégrations → Ajouter une intégration est l'endroit où les intégrations personnalisées sont découvertes et installées pour la première fois. L'onglet Paramètres → Plateforme → Packs → Catalogue permet de suivre l'état d'installation pour tous les types de contenu et d'appliquer les mises à jour.

Dans le marketplace, les intégrations personnalisées synchronisées apparaissent sous Depuis votre catalogue de packs :

• Pas encore installée — affiche un bouton Ajouter ; cliquer dessus installe et active l'intégration immédiatement.
• Déjà installée et à jour — affiche un indicateur À jour et reste dans le groupe du catalogue de packs. Cliquer sur la carte ouvre la vue de configuration du fournisseur.
• Mise à jour disponible — affiche un badge Mise à jour. Cliquer sur l'action renvoie directement vers Paramètres → Plateforme → Packs pour examiner l'impact sur les workflows et appliquer la mise à jour. Voir Gestion des versions de packs.

L'installation d'un pack entier (y compris ses types de contenu non-intégration tels que l'ontologie, les workflows et les sources de données) se fait via l'action Installer dans Paramètres → Plateforme → Packs → Catalogue.

L'ajout d'une intégration depuis le marketplace l'active immédiatement — l'action explicite de l'administrateur est la révision. La politique de signature contrôle les flux non interactifs :

Limite de taille de pack pour les artefacts d'intégration : 8 Mo par bundle.tar.gz. Les intégrations plus volumineuses doivent utiliser le téléversement manuel (50 Mo). Voir le guide de création de packs pour la structure complète des sous-répertoires et la déclaration pack.json.

Politiques de signature

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

cosign-keyless (recommandé)

signature:
  kind: cosign-keyless
  certificateIdentityRegexp: "https://github.com/acme/scrydon-packs/.*"
  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 — un pack signé 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 }.

Dépannage

verify_failed

La vérification de signature a échoué pour un ou plusieurs artefacts de pack.

• 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-packs/.*).
• 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 le pack a été signé après avoir été poussé 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 de pack 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

Le pack a été récupéré et vérifié mais son installation a échoué.

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

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

Cette source a été initialisée via packSources: 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.

Un pack retraité est revenu / un pack est absent du catalogue

Les packs gérés par une source suivent le catalogue de la source : un pack retraité qui est encore listé dans scrydon.yaml est restauré lors de la prochaine synchronisation (voir Le catalogue source fait autorité). Inversement, si un pack attendu est absent, vérifiez qu'il est listé 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é — l'état retraité/restauré suit ensuite la source automatiquement.