Publish a Governed Pipeline
Use this guide when a Pipeline Authoring draft is ready to move from a reviewed definition into a repository and, for Airflow, a deployable package. Publication is version-bound: Qarion publishes the exact saved definition version that passed the required checks.
Before You Start
Confirm that the workspace has a repository and target branch, that the draft targets Airflow or Dagster, and that you have manage access. Save or revert dirty editor changes before validating. Unresolved editor conflicts prevent Qarion from proving that the reviewed code matches the code it will publish.
Dagster is compile-and-validate focused in the current release. The publication and packaged-deployment steps in this guide apply to Airflow.
1. Review the Current Version
Open the definition and check the following surfaces:
- Plan review shows the approved tasks, dependencies, write scopes, acceptance criteria, and required evidence.
- Files shows the repository-backed draft and any additions, edits, or deletions.
- Graph shows nodes, dependencies, and the DAG README.
- Audit history shows the agent runs, decisions, validation attempts, and version changes that produced the current draft.
If the draft has advanced since a review or validation run, use the current version rather than relying on evidence from the older version.
2. Run Authoritative Validation
Run validation from the authoring cockpit. Publication requires every configured section to pass: compiler, static code, support tests, dependencies, runtime resources, and sandbox checks. A warning or a requested check reported as Skipped does not count as passed.
When validation finds a problem, use the recovery action shown beside the diagnostic. Qarion can route findings to code repair, plan revision, user input, environment resolution, transient retry, or unsafe-scope review. A repaired candidate is retained only when it improves the result without introducing a new critical, security, or policy blocker.
Repository commands can require a separate approval. Review the exact command, working directory, bounded paths, and network intent before approving it.
3. Confirm Generation Readiness
The readiness summary should show Ready for publication. Other states need attention:
| Status | What to do |
|---|---|
| Not validated | Run validation for the current saved version. |
| Stale | Re-run validation after the draft, target, fingerprint, or policy change. |
| Blocked | Resolve the failed, warned, or skipped requirement shown in the inspector. |
| Failed validation | Repair the candidate or selectively save only the files you intend to keep. |
| Unsupported | Use a supported operation for the selected runtime target. |
Partial execution slices cannot be published. Complete every required execution unit and resolve pending decisions before continuing.
4. Publish
Open Publish, review the target repository, branch, generated files, and merge-request details, then start publication. Publication revalidates and locks the immutable version before its first Git mutation.
The operation continues if you leave or reload the page. Return to the Publish inspector to see validation, Git, merge-request, and managed-resource checkpoints. Cancellation is available only before the first Git mutation. Retry creates an audited child attempt rather than overwriting the failed run.
If the draft advances while an older version is publishing, Qarion preserves the older result but marks it stale instead of treating the newer draft as published.
5. Use the Airflow Deployment Artifact
A successful Airflow publication creates an immutable ZIP from the validated
version. The artifact contains the DAG, its transitively imported local modules,
package initializers, explicit runtime files, the selected dependency manifest,
hash-verified wheel contents, and .qarion/deployment.json evidence. It is
stored separately from the publication branch.
Choose the package mode that matches the Airflow runtime:
- Extracted is the default. Extract the archive into the DAG runtime. This mode supports pure-Python dependencies and compatible native wheels.
- ZIP import places the ZIP directly in
DAGS_FOLDER. Use it only for pure-Python dependencies; Qarion rejects native extensions in this mode.
The Publish inspector shows the package mode, dependency manifest, lock identity, checksum, size, compatibility findings, and authorized download action. Keep the checksum with deployment evidence so operators can verify that the runtime package matches the version approved in Qarion.
Troubleshooting
- Manifest requires clarification: set the supported repository-relative requirements manifest explicitly when two candidates exist at the same nearest directory.
- Native wheel rejected: use extracted mode and confirm the configured Airflow Python and platform target matches the wheel.
- Sandbox is skipped or disabled: ask an administrator to configure the hardened validation runner. Publication fails closed.
- Publish button remains blocked: check for dirty files, stale validation, incomplete execution units, unresolved decisions, or a draft that differs from the accepted result.
See Pipeline Authoring for workspace, graph, agent, repair, and reliability concepts. Developers automating this lifecycle can use the Pipeline Authoring API.