Intégrer une intégration personnalisée dans un Pack

Livrez une intégration personnalisée dans un Pack Scrydon pour que les sources de packs la distribuent automatiquement via la synchronisation Git/OCI

Un pack peut contenir une ou plusieurs intégrations personnalisées grâce au type de contenu integration. Une fois le pack installé, l'intégration personnalisée apparaît dans Paramètres → Plateforme → Intégrations → Personnalisées — aucune étape de téléversement séparée n'est nécessaire. Combinez cette approche avec les sources de packs (synchronisation Git/OCI) pour un pipeline de livraison entièrement automatisé : poussez sur Git, Scrydon récupère le pack et l'intégration atterrit dans le catalogue. Pour comprendre comment les versions se propagent de la release vers le runtime (épinglages, politiques de mise à jour, révision des changements cassants), consultez Versionnement des packs.

Cette page traite de l'intégration d'un artefact d'intégration déjà construit dans un pack. Pour construire l'artefact d'intégration lui-même, consultez le guide d'authoring des intégrations.

Quand utiliser cette approche

Utilisez un type de contenu de pack integration lorsque :

Vous souhaitez livrer une intégration personnalisée depuis un dépôt Git ou un registre OCI sans téléversement manuel à chaque release.
Un pack que vous distribuez nécessite une capacité de vendor personnalisée (LLM, STT, outils, blocs) et vous voulez que l'intégration et l'ontologie/les workflows/le process-flow s'installent ensemble.
Vous voulez que le CI/CD contrôle la version de l'intégration et que Scrydon la récupère automatiquement à chaque release.

Utilisez la porte de téléversement manuel lorsque l'artefact d'intégration dépasse 8 Mo (limite de livraison par pack) ou lorsque vous n'avez pas de source de pack configurée et souhaitez une installation ponctuelle.

Prérequis

Un artefact d'intégration construit — bunx @scrydon/sdk-authoring integrations build produit dist/{vendorId}-{version}.bundle.tar.gz. Renommez-le en bundle.tar.gz pour le sous-répertoire du pack.
Un projet de pack existant avec pack.json. Si vous n'en avez pas, créez-en un : bunx @scrydon/sdk-authoring pack init my-pack --outDir ./packs.

Structure du sous-répertoire

Pour chaque intégration à inclure, créez un sous-répertoire (nommé par convention integration-<vendorId>) contenant exactement deux fichiers :

packs/my-pack/
├── pack.json
├── ontology/                  # optionnel — d'autres types peuvent coexister
│   └── manifest.json
└── integration-acme-crm/      # un sous-répertoire par intégration
    ├── manifest.json
    └── bundle.tar.gz

`integration-acme-crm/manifest.json`

{
  "vendorId": "acme-crm",
  "version": "1.2.0"
}

Champ	Règles
`vendorId`	Slug en minuscules : `^[a-z0-9][a-z0-9-]*$`, 1–100 caractères. Doit correspondre à l'`id` déclaré dans l'artefact d'intégration.
`version`	Chaîne semver (ex. `1.2.0`, `2.0.0-beta.1`). Doit correspondre à la version déclarée dans l'artefact.

Le bundler (scrydon-pack build) valide ce manifeste et confirme que bundle.tar.gz est présent et dans la limite des 8 Mo. Le manifeste interne est re-validé par la plateforme au moment de l'installation.

`bundle.tar.gz`

L'artefact d'intégration construit — identique au fichier accepté par la porte de téléversement manuel. Taille maximale : 8 Mo par artefact livré via un pack. Les artefacts de plus de 8 Mo doivent être téléversés via la porte de téléversement manuel (limite de 50 Mo).

Déclarer l'entrée dans `pack.json`

Ajoutez l'entrée d'intégration dans contents[] et incluez "integration" dans installOrder :

{
  "manifestVersion": 1,
  "package": {
    "id": "acme-crm-pack",
    "name": "Acme CRM Pack",
    "version": "1.0.0"
  },
  "installOrder": ["ontology", "integration"],
  "contents": [
    {
      "kind": "ontology",
      "path": "ontology",
      "version": "1.0.0",
      "required": true
    },
    {
      "kind": "integration",
      "path": "integration-acme-crm",
      "version": "1.2.0",
      "required": true
    }
  ]
}

"integration" est un type répétable — un seul pack peut inclure plusieurs entrées d'intégration, chacune dans son propre sous-répertoire avec son propre manifest.json et bundle.tar.gz. Définissez "required": false pour les intégrations qui sont des extensions optionnelles.

Construire et publier

# Valider et construire le .scrydon-pack.tar.gz
cd packs/my-pack
bunx @scrydon/sdk-authoring pack build .

# Le résultat est : dist/acme-crm-pack-1.0.0.scrydon-pack.tar.gz

Le bundler valide :

integration-acme-crm/manifest.json parse conformément à IntegrationContentManifestSchema.
integration-acme-crm/bundle.tar.gz existe et fait ≤ 8 Mo.
vendorId et version dans le manifeste du sous-répertoire sont cohérents avec l'entrée dans pack.json.

Publiez via les sources de packs (recommandé pour le CI) ou par téléversement manuel dans Paramètres → Plateforme → Packs.

Politique d'activation

Lorsqu'un pack contenant une entrée d'intégration est installé, le statut initial de l'intégration dépend du mode d'installation :

Déclencheur d'installation	Statut d'activation
Action d'administrateur explicite (Ajouter/Mettre à jour dans la marketplace, Installer dans le catalogue)	Actif — l'action d'installation de l'administrateur constitue la révision
Installation non interactive depuis une source `cosign-keyless` / `cosign-key`	Actif — la vérification cosign est la porte de confiance
Installation non interactive d'un artefact non signé	En attente de révision — l'administrateur org doit approuver avant que l'intégration soit disponible

Aujourd'hui, tous les chemins d'installation sont des actions d'administrateur explicites, donc les intégrations s'activent immédiatement ; les lignes En attente de révision s'appliquent aux flux automatisés futurs (ex. mise à jour automatique lors de la synchronisation d'une source).

Les intégrations En attente de révision apparaissent dans Paramètres → Plateforme → Intégrations → Personnalisées avec un bouton Activer. Une fois activées, elles sont disponibles dans l'éditeur de workflows.

Pour les installations non interactives, la politique de signature de la source est la porte de confiance. Les sources signées avec cosign sont déjà vérifiées par le réconciliateur au moment de la synchronisation, donc le champ de politique est fiable. Voir Politiques de signature pour configurer la signature cosign-keyless pour votre source de pack.

Flux d'installation (ce qui se passe lors de `packs/install`)

La plateforme lit la ligne du catalogue pour ce pack, qui contient les entrées de contenu inspectées — pour les entrées d'intégration : l'identité du vendor, la référence de l'artefact stocké et l'empreinte sha256 de l'artefact.

La plateforme consulte la signaturePolicy de la source de pack pour déterminer sourceSigned. Les lignes sans source (téléversements manuels) sont traitées comme non signées.

La plateforme vérifie la politique de gouvernance des intégrations de l'organisation. Si vendorId est dans blockedVendorIds, l'entrée échoue avec une erreur structurée vendor_blocked. Les autres entrées du pack continuent à s'installer.

La plateforme charge les octets de l'artefact depuis le stockage objet, recalcule le hachage sha256 et le compare à l'empreinte enregistrée au moment de l'entrée dans le catalogue. Un écart fait échouer l'entrée avec integration_artifact_hash_mismatch.

La plateforme inspecte l'artefact (le même moteur de validation que le téléversement manuel) pour extraire le manifeste interne. L'identité du vendor (vendorId, version) est comparée à l'entrée du catalogue. En cas de correspondance, l'intégration personnalisée est enregistrée avec le statut dérivé de la politique.

Réinstaller le même pack avec le même hachage d'artefact est une opération neutre pour l'entrée d'intégration — la ligne existante est retournée telle quelle. Un hachage modifié met à jour la ligne et redérive le statut.

Gouvernance et vendors bloqués

Si votre organisation a défini blockedVendorIds dans la politique de gouvernance des intégrations, tout install de pack incluant un vendor bloqué fait échouer cette entrée avec une erreur structurée. L'erreur est exposée dans le résultat d'installation du pack ; les autres entrées (ontologie, process-flow, etc.) ne sont pas affectées.

Pour débloquer un vendor, supprimez-le de blockedVendorIds dans Paramètres → Plateforme → Intégrations → Gouvernance, puis relancez l'installation du pack.

Dépannage

`integration_validation_failed` lors de l'inspection du pack

Le integration-<slug>/manifest.json a échoué à la validation du schéma.

Vérifiez que vendorId est un slug en minuscules (^[a-z0-9][a-z0-9-]*$).
Vérifiez que version est un semver valide (1.2.0, pas v1.2.0 ni latest).
Exécutez bunx @scrydon/sdk-authoring pack validate . localement pour des erreurs détaillées.

`integration_artifact_missing` lors de l'installation du pack

La ligne du catalogue n'a pas de référence d'artefact stocké — l'artefact n'a pas été persisté lors de l'entrée du pack dans le catalogue. Cela arrive pour les lignes de catalogue créées avant que la plateforme prenne en charge les entrées de pack d'intégration. Re-synchronisez la source (cliquez Synchroniser maintenant) pour réécrire la ligne du catalogue avec l'artefact.

`vendor_blocked` lors de l'installation du pack

La politique blockedVendorIds de l'organisation inclut ce vendorId. Supprimez le vendor de la liste de blocage ou reconstruisez le pack sans cette entrée d'intégration.

`integration_identity_mismatch` lors de l'installation du pack

Le vendorId ou la version dans le manifeste interne de l'artefact ne correspond pas à ce que le manifest.json du sous-répertoire du pack avait déclaré. Reconstruisez l'intégration avec des champs d'identité correspondants.

L'inspection du pack rejette `bundle.tar.gz` avec `disallowed_extension`

Cela signifie que bundle.tar.gz ne se trouve pas dans un sous-répertoire déclaré kind: "integration". Assurez-vous que contents[] du pack contient une entrée avec "kind": "integration" et un path correspondant au sous-répertoire contenant le fichier.

Intégrer une intégration personnalisée dans un Pack

Sur cette page