ADR-028: Out-of-Tree Plugin Obligations¶
Audience: third-party — see ADR index.
Status: Accepted (SDK publication, manifest schema, export pipeline and install contract pending — see Consequences → Follow-on work) Date: 2026-10-07 Deciders: Portal team Scope: BU-approved third-party Automation Portal plugins whose source lives outside this repository.
Context¶
ADR-010 through ADR-019 bind factory plugins. Several of those ADRs still describe in-tree paths (plugins/backstage-<pluginId>, packages/app). Third-party plugins are not authored here. They load as RHDH dynamic plugins against the Portal SDK contract. Published @ansible/portal-* npm packages are specified and not yet shipped.
Without an explicit out-of-tree ADR, authors copy workspace:^, embed portal-extension-api, or patch host UI.
Decision¶
Common ADRs still apply. This ADR adds obligations that exist only because the plugin is out of tree.
- Other repository. Do not add a third-party plugin workspace to this monorepo. Do not use
workspace:^. When the SDK is published, install the scoped packages below; until then this install path is not yet — fail closed, do not invent a private substitute. - Author vs host packages. Canonical specified names (scope
@ansible/, not yet on npm):@ansible/portal-extension-common,@ansible/portal-extension-api,@ansible/portal-plugin-sdk,@ansible/portal-plugin-node. Do not depend on@ansible/portal-extension-host,portal-core, orportal-health-backend. - Module Federation singleton. Declare
@ansible/portal-extension-apias a frontendpeerDependency. Never--embed-packagethe registry. Two copies of the contribution registry means contributions never appear. Hostportal-coremust load first. Backend@ansible/portal-plugin-nodeis not an MF singleton. - Do not patch the host. Do not add widgets to a hardcoded create-wizard field list, edit installer plugin lists, or open a Portal PR to wire a one-off route. Register
scaffolderFieldExtensionsand capabilities against the published contract. - No
packages/appcomposition. Out-of-tree plugins cannot be statically imported by the upstream app. Dynamic plugin load is the path. - Escalate only for host contract changes. A new Experience, Blueprint family, semantic region, or host
apiVersionneeds Portal engineering. Placement inside an existing Experience is host policy. - Packaging and reusable CI are unspecified. Do not invent a Containerfile, Konflux pipeline, or
dynamic-plugins.yamlsnippet as if it were the official publish path. Fail closed and record the gap.
Consequences¶
- Third-party onboarding can run without cloning private SDLC trees.
- In-tree factory plugins use workspace protocol and the application workspace's native composition; legacy app guards remain a compatibility concern. Neither is the proposed out-of-tree distribution path.
- Follow-on work: published npm versions of the SDK, generic scaffolder field-registry merge, and a documented export pipeline.