Upload validates, stages, and durably qualifies a Connected System candidate on the dataplane. Deploy promotes that qualified candidate through Miso Controller when managed platform promotion is required. The upload job, not the lifetime of your terminal or browser request, is the qualification record.
Role Assistant packages: For Role Assistants,
uploadanddeployshare one dataplane promote path with--env(dev/tst/pro) — settings + Evidence, not this Connected System Miso deploy model. See Manage Role Assistant packages.
Prerequisites
- Local validate green:
aifabrix validate <systemKey> aifabrix auth statusgreen (user or CI app credentials)
Where it lives
| Action | Target |
|---|---|
| Upload | Dataplane candidate qualification; optional operations, trust, and governance checks are selected here |
| Deploy | Controller-managed promotion of the qualified current candidate (aifabrix deploy) |
| Online truth | aifabrix show <systemKey> --online |
Local files under integration/<systemKey>/ are source of truth until upload.
How to set
- Preflight validate:
aifabrix validate <systemKey>
aifabrix json <systemKey>
- Submit and wait for qualification:
aifabrix upload <systemKey>
The CLI waits for the durable job by default. To detach immediately or return to an existing job without submitting another candidate:
aifabrix upload <systemKey> --no-wait
aifabrix upload <systemKey> --resume <jobId>
Ctrl-C or a CLI wait timeout detaches; it does not cancel server work. Keep the job id and use --resume to see its terminal result. --verbose expands upload detail; --probe runs post-publish runtime checks and is not a mandatory preflight or a non-mutating dry run. For a local-only preflight, use upload --dry-run.
Plain upload qualifies the candidate without the optional operations, trust, or governance checks. Select those checks on the upload job when your promotion policy requires them:
aifabrix upload <systemKey> --gate operations
aifabrix upload <systemKey> --gate operations,trust
aifabrix upload <systemKey> --gate governance --subject-email scoped-user@example.com
aifabrix upload <systemKey> --gate full --subject-email scoped-user@example.com
Allowed gate values are operations, trust, governance, full, or a comma-separated combination. full selects all three checks.
For a system's first publish, complete protection and governance prerequisites before selecting those gates. A gate result applies to the candidate it qualified; changed content requires another upload and requalification.
- Compare online vs local:
aifabrix show <systemKey> --online
- Deploy (when controller promotion is required):
aifabrix deploy <systemKey>
Deploy uses the server's qualified current input for a fast status promotion. Missing, stale, or failed proof after qualification has been adopted fails closed: upload the changed candidate again and wait for its result. Deploy does not rerun the client-side certification ladder; deploy --gate is a compatibility no-op, not a force bypass. A system never qualified by upload may still use a legacy server promotion path, but that is not the preferred workflow.
Builder API upload and deploy calls return an accepted operation with a resumable job or deployment identity instead of keeping a web request open until completion. Read the operation status after acceptance or a browser refresh; Builder forwards Dataplane qualification and Miso deployment truth rather than inventing a separate success state. An accepted response is not a terminal success.
- Optional diagnostic tests:
aifabrix test-integration <systemKey>
aifabrix test-e2e <systemKey>
Typical promotion sequence:
validate → upload (wait for qualified result) → show --online → deploy
Defaults and examples
| Command | When |
|---|---|
upload --dry-run |
Local payload preflight without network submission |
upload |
Durable qualification; wait for its terminal result by default |
upload --no-wait / upload --resume <jobId> |
Detach from and later rejoin the same job |
upload --gate operations,trust |
Publish and run only the selected checks |
upload --gate full |
Publish and run operations, trust, and governance after all prerequisites exist |
deploy |
Managed promotion of qualified current input |
show --online |
Drift check before certify |
Credentials: upload may push credential references — if denied, fix permissions and kv:// resolution (Configure authentication).
Upload publishes every datasource key with root entityType, resourceType, primaryKey, and indexed externalId — validation failures on unknown resourceType may indicate catalog sync lag, not pipeline outage.
Role catalog gate (fail-closed)
Purpose: business and management set access boundaries in one Role catalog. Development teams reuse those roles on applications and Connected Systems — they do not invent a parallel access model per system.
Modern identity groups are already hard to govern. AI Fabrix intentionally avoids each integration or AI surface creating its own role/group reality. Publish fails closed so a system cannot “bring its own” roles that were never agreed in the catalog.
Applications and Connected Systems declare roles in RBAC. Every role key referenced there must already exist in the Controller Role catalog.
Business sets Role catalog
→ Integrator references role keys in RBAC
→ Catalog check on deploy / upload
→ Missing key → fails (no invent-on-publish)
→ Add or activate role in Controller → retry
The platform does not create missing catalog roles during deploy or upload. Typical fix: open Roles in the Controller, add or activate the key (or use an existing seeded key), then probe again.
Everyone (aifabrix-everyone) is one catalog role used for LLM and platform-search consume — same rule as any other key: grant it only because it already exists in the catalog, not because a system invented it. See AI Fabrix roles.
Sanitized probe success shape:
{
"success": true,
"systemKey": "example-crm",
"phase": "probe",
"datasources": ["example-customers"]
}
Follow and stop publishing work
Open Connected Systems → Jobs to find qualification and publishing jobs by
job ID or system key. Open the job to inspect its steps and recorded outcome.
Keep the accepted job ID when the CLI disconnects; use upload --resume <jobId>
to follow that job rather than submit another upload.
An authorized operator can request Stop job or Stop publishing, with a
reason. Stop requested is not a completed stop. Stopped confirms the job
ended before publication effects; Needs review means an effect may have
occurred. Inspect the job and resulting system state before retrying. A timeout
or stop request does not prove rollback. Continue in background only closes
the dialog. Older jobs may require effect review instead of supporting Stop.
Validate
aifabrix upload <systemKey>
aifabrix show <systemKey> --online
Do not run certification pillars on unpublished local-only config.
Common mistakes
| Mistake | Fix |
|---|---|
| Upload without validate | Fix schema locally first |
Treating --probe as a non-mutating preflight |
Use --dry-run; probe runs checks after publish |
| Assuming deploy = upload | Use upload for dataplane publish in dev |
| Assuming plain upload runs governance | Select --gate governance or --gate full on upload after governance prerequisites exist |
Expecting deploy --gate to recertify |
Select gates on upload; deploy consumes existing qualification |
| Stale online after edit | Re-upload + show --online |
| RBAC role key missing from Role catalog | Add/activate the role in Controller first; do not invent roles per system at publish time |
| Listing every Role Assistant on LLM/search RBAC | Grant consume to catalog Everyone instead of a private role list — AI Fabrix roles |
Limits
Deploy permissions and environment promotion policies vary by organization — confirm with your platform operator which path applies in tst/pro.
Upload publishes key, displayName, systemKey, entityType, resourceType, and companion bands from local JSON — if show --online differs from git, re-run repair --dry-run before blaming the pipeline. Upload qualification does not replace vendor credential or sync-configuration diagnostics; run test-integration before test-e2e when investigating those paths. Single-datasource upload via datasource upload still requires root systemKey and resourceType on the file.
Post-upload drift check — compare online datasource key list to application.yaml:
aifabrix show <systemKey> --online
aifabrix validate <systemKey>
If validation fails on externalId or primaryKey, fix datasource JSON locally before retrying upload — the pipeline will not patch missing join identity during publish.
Controller deploy promotion may lag dataplane upload in shared dev environments — run show --online on the environment you intend to certify, not only the machine where upload succeeded.
Protection manifests under integration/.protection/ upload separately — integration upload success does not publish dimension grants; follow Protection manifests and upload before verify-governance.
Credential push during upload may be denied by platform policy while schema publish succeeds — investigate the qualification result and integration tests before announcing deploy completion to operators.
Record show --online snapshots in change tickets when operators approve publish — diffing online vs git is a useful drift signal when qualification passed but integration tests fail post-upload.
The durable qualification contract is supported, but live cross-system reload-equivalence acceptance is still being validated in the current environment. Do not interpret one successful upload/deploy as blanket production reliability across every connector.