/drasi

Delivery bundle

Use this bundle for CI/CD, GitOps, release artifacts, environment promotion, deployment order, and rollback evidence for Drasi projects.

Delivery principle

Drasi resource deployment should be repeatable, reviewable, environment-aware, and validated end to end before promotion.

New-project repository layout

Prefer a clear separation like:

drasi/
  sources/
  queries/
  reactions/
  validation/
  environments/
    dev/
    test/
    prod/

Keep provider-specific secrets out of source control. Store only secret references, environment parameters, or non-sensitive local development placeholders.

Deployment order

Apply in forward dependency order:

1. Runtime infrastructure.
2. Source-system prerequisites.
3. Sources.
4. ContinuousQueries.
5. Reactions.
6. Validation tests.
7. Observability and release evidence.

Rollback or delete in reverse dependency order:

1. Reactions.
2. ContinuousQueries.
3. Sources.
4. Runtime infrastructure only when required.

CI/CD gates

Use gates appropriate to the repository, such as:

• YAML/schema validation.
• Secret scanning.
• Version pin checks.
• Linting for banned production latest tags and unbounded crate/action versions.
• Skill/package validation with scripts/validate-skill-package.py after changes to the skill itself.
• Provider schema verification note.
• Environment parameter validation.
• Dry-run or plan step when the selected deployment tool supports it.
• Apply to dev or ephemeral environment.
• End-to-end validation bundle.
• Manual approval before production or destructive recovery.

Release artifact contents

Store or publish:

• Runtime form and versions.
• Image tag and digest.
• Source/query/reaction manifests or API payloads.
• Environment parameters excluding secrets.
• Validation output.
• Observability links.
• Rollback commands or workflow.
• Known risk notes.

Promotion rules

Promote the same reviewed artifact between environments. Do not regenerate production manifests with unreviewed differences.

Allow environment-specific differences only for:

• Resource names and suffixes.
• Secret references.
• Hostnames and network paths.
• Sizing and scaling.
• Logging retention.
• Explicitly approved feature flags.

Failure handling

If deployment fails:

1. Stop promotion.
2. Preserve logs and release artifacts.
3. Identify the first failed dependency.
4. Avoid broad retry loops that hide root cause.
5. Route to operations for diagnosis.
6. Route to recovery before any destructive cleanup.

Drasi version-compatibility CI gate

Every PR that touches Drasi manifests, Drasi Server configuration, or drasi-lib Rust code MUST pass these PR-time checks. Each check fails the PR when not satisfied.

1. Pinned CLI version matches the target platform release. Parse drasi CLI version from versions.md and confirm it matches the platform release in the same file.
2. Manifest apiVersion matches the installed platform. Every Source/ContinuousQuery/Reaction manifest under drasi/ declares an apiVersion accepted by the pinned platform release.
3. drasi-lib crate matches the AI-context stable version. The drasi-lib version in Cargo.toml matches the current_stable_version field from drasi-context.yaml, OR an approved exception is documented in versions.md.
4. MCP spec version is declared and matches the client. The MCP Reaction config declares spec version 2025-03-26 or higher, and any consumer/agent capability advertises the same version.
5. Image digest resolves and matches versions.md. Every Drasi Server (or related) image reference uses @sha256: digest pinning, the digest resolves on the registry, and it matches the digest captured in versions.md.

Pseudocode example of the pinned-CLI check:

# .github/checks/drasi-cli-pin.sh
set -euo pipefail
pinned_cli="$(awk -F'`' '/Drasi CLI version/ {print $2}' versions.md)"
ci_cli="$(drasi version)"   # docs document plain `drasi version`; strip any prefix/suffix your CI adds
if [ "$pinned_cli" != "$ci_cli" ]; then
  echo "Pinned CLI ($pinned_cli) does not match CI CLI ($ci_cli)" >&2
  exit 1
fi

Equivalent checks for apiVersion, MCP spec, and image digest follow the same pattern: parse versions.md, diff against the artifact under review, fail on mismatch.

Release-notes subscription discipline

Drasi is pre-1.0 and moves quickly. Subscribe to upstream release notifications and run a quarterly diff review so breaking changes never surprise a delivery pipeline.

Upstream sources to monitor:

• drasi-project/drasi-platform GitHub releases - platform release line, apiVersion bumps, CLI compatibility.
• drasi-project/drasi-server GitHub releases (and the GHCR image registry until tagged releases ship) - server behaviour, REST endpoint changes, config schema.
• drasi-lib crate on crates.io - embedded Rust API changes.
• The published drasi-context.yaml (linked from https://drasi.io/reference/context/) - authoritative current_stable_version, schemas, and AI-context surface area.

Operational discipline:

• Use GitHub's per-repository release-notification subscription (Watch -> Custom -> Releases) for every drasi-project/* repository the delivery pipeline depends on.
• Subscribe a delivery channel (mailing list, Teams channel) so notifications are not lost in an individual inbox.
• Run a quarterly diff review of drasi-context.yaml, platform CHANGELOG, and server CHANGELOG. Record the diff in the next release artifact and update versions.md accordingly.
• On any notified release, run the apiVersion migration playbook (see bundles/sources/guide.md) and the upgrade-evidence template before promoting past dev.

Release gate - SLO and load-test wiring

The version-compatibility CI gate above is necessary but not sufficient. Production-bound PRs MUST also produce the following evidence at merge, drawn from the named source bundle:

Operational rules:

• The PR check fails if any row above is missing or below baseline; do not merge to a production-bound branch.
• If a baseline is not yet set for your environment, set one (see bundles/observability/guide.md) before opening a production-bound PR - an unset baseline is not a free pass.
• The version-compatibility gate continues to run alongside these gates; both must pass.