Git Template Sources

A template source is a Git repository whose *.tensor9.{tf,sh,kubectl} and *.t9.{tf,sh,kubectl} files become Tensor9 BYOC ops command templates in your control plane. You register the source once; later, as the repo evolves, resync compares the repository with your imported templates. A separate upgrade applies selected additions, modifications or removals from source tracking. This is the canonical way to maintain a library. The open-source tensor9ine/cmdlib repo is laid out exactly this way and is a good starting point if you’re new to authoring templates.

Register a Git template source and import selected files. Resync reports unchanged, modified, new and removed files without updating templates. A separate upgrade fetches the source again and applies selected changes. Arrows show the operator command sequence.

Resync compares source files with tracked template hashes. Upgrade is a separate command that fetches the source again and applies the selected actions. Review that source content and the selected files before updating your template library. Three properties keep authoring sane:

Templates can follow your code review process. Use the repository review policy to check changes before importing or updating templates.
Resync surfaces drift. When the repo lands new templates or modifies existing ones, tensor9 ops template source resync shows the four-bucket diff (unchanged, modified, new, removed) without committing anything.
Upgrades are explicit. tensor9 ops template source upgrade is a separate step. Diff first, then apply only the picks you want, scoped by file or action kind.

A reference layout

The cmdlib repo groups templates by category. Each subdirectory contributes one template per .tensor9.* file inside it:

src/
  aws/
    find-idle-instances.tensor9.tf
    list-public-s3-buckets.tensor9.tf
    ...
  k8s/
    drain-node.tensor9.tf
    scale-deployment.tensor9.tf
    ...
  linux/
    disk-usage.tensor9.tf
    host-info.tensor9.tf
    ...
  darwin/
    disk-usage.tensor9.tf
    host-info.tensor9.tf
    ...

Both linux/ and darwin/ contain a disk-usage.tensor9.tf. They coexist because Tensor9 BYOC prefixes the parent directory name onto the imported template, producing linux-disk-usage and darwin-disk-usage as distinct templates. See “Conflict resolution” below for the cases where the prefix alone does not disambiguate.

Registering a source

tensor9 ops template source create \
  --sourceType GitHub \
  --sourceUrl https://github.com/tensor9ine/cmdlib \
  --appName my-app \
  --sourceName cmdlib

The action uses gh to clone the selected branch, discovers matching files in the selected directories and sends their raw bytes to your control plane for parsing and template creation. It then records the source and its imported template IDs. Useful flags:

Flag	Purpose
`--branch`	Override the branch (default: the repo’s default branch).
`--dirs`	Comma-separated directories to import initially (default: discovered directories containing a supported template file).
`--dryRun`	Discover and print what would be imported. No control-plane writes.
`--conflictPolicy`	How to handle template-name conflicts in the target app. See below.

gh auth login must succeed first. The action will fail with a clear message if the GitHub CLI is missing or unauthenticated.

Conflict resolution

The persisted template name is the dir-prefixed file stem (linux-disk-usage from linux/disk-usage.tensor9.tf). A name conflict happens when that stem already exists in the target app because, say, the same source was registered before and you are re-importing. --conflictPolicy controls the bulk behavior:

Value	Effect
`fail` (default)	Stop at the first conflicting name. Templates already created by this attempt remain; the source record is created after the import loop completes.
`skip-all`	Skip every conflicting file. The non-conflicting subset still imports.
`duplicate-all`	Auto-rename each conflicting file with a `-N` suffix (`linux-disk-usage-2`, then `-3`, etc.).

Example:

# Re-import cmdlib, dropping anything we already track and importing only the new files
tensor9 ops template source create \
  --sourceType GitHub \
  --sourceUrl https://github.com/tensor9ine/cmdlib \
  --appName my-app \
  --sourceName cmdlib-v2 \
  --conflictPolicy skip-all

The action’s output lists the skipped or renamed files explicitly so you can audit what landed.

Resyncing against HEAD

tensor9 ops template source resync --sourceName cmdlib

Resync clones the repo, lifts each file’s spec, and reports the four-bucket diff against what’s already imported:

Bucket	Meaning
`Unchanged`	Tracked template whose source file at HEAD has the same content hash. No action needed.
`Modified`	Tracked template whose source file at HEAD has a different content hash. Run `tensor9 ops template source upgrade` to mint a new lineage version.
`New available`	File at HEAD that no tracked template owns. Run `tensor9 ops template source upgrade --actions add` to import.
`Removed upstream`	Tracked template whose source file vanished from HEAD. Run `tensor9 ops template source upgrade --actions retire-here` to drop the source binding.

Resync is read-only; it never persists anything. Run it as often as you like.

Resync walks the whole repo, not just the directories you selected at register time. If a new sibling directory landed upstream after you registered (a darwin/ next to your originally-selected linux/), its files surface as New available automatically. You do not need to re-register the source to track new dirs.

Applying the diff: upgrade

tensor9 ops template source upgrade --sourceName cmdlib

By default tensor9 ops template source upgrade fetches the source again and applies all matching actions: evolve modified templates, import new files and remove source bindings for missing files. The repository can change between resync and upgrade; the earlier diff does not freeze the bytes that upgrade imports. Modified templates receive a new lineage version and content hash. Existing command records retain their submitted template references. Check approval coverage for the selected version and values before submitting another command.

Scoping with `--only` and `--actions`

Two filters narrow what the upgrade does:

# Only evolve modified templates; don't add new files or retire missing ones
tensor9 ops template source upgrade \
  --sourceName cmdlib \
  --actions upgrade

# Only add newly-discovered files; leave existing tracked templates alone
tensor9 ops template source upgrade \
  --sourceName cmdlib \
  --actions add

# Apply the diff but only for two specific files
tensor9 ops template source upgrade \
  --sourceName cmdlib \
  --only linux-disk-usage.tensor9.tf,linux-host-info.tensor9.tf

--actions accepts any subset of upgrade, add, retire-here. --only restricts to a CSV of file names matching what tensor9 ops template source resync listed.

What “retire-here” means

When a tracked file vanishes upstream, retire-here attempts to deprecate its current template version, then removes its source binding. If deprecation fails, the action warns and still removes the binding. For example, a lineage cannot deprecate its only active version. The template lineage remains in your control plane. Removing a source binding is a library-maintenance action; manage template versions and customer approvals separately.

Inventory

# All sources you've registered
tensor9 ops template source list

# A single source's full detail
tensor9 ops template source retrieve --sourceName cmdlib

retrieve shows the GitHub coordinates, last-synced commit, selected directories, and the imported template id list.

Retiring a source

tensor9 ops template source retire --sourceName cmdlib

This removes the source record and leaves its imported template lineages intact. They are no longer tracked through that source for resync or upgrade. Manage the templates and their approvals separately. Use --auto to skip the confirmation prompt in scripts.

End-to-end example

# 1. Register the public cmdlib repo as a template source for `my-app`
tensor9 ops template source create \
  --sourceType GitHub \
  --sourceUrl https://github.com/tensor9ine/cmdlib \
  --appName my-app \
  --sourceName cmdlib

# 2. Some weeks later, a new `darwin/` dir landed upstream.
#    See what's changed:
tensor9 ops template source resync --sourceName cmdlib

# 3. Import newly discovered files; leave tracked templates unchanged
tensor9 ops template source upgrade \
  --sourceName cmdlib \
  --actions add

# 4. Review what you now expose:
tensor9 ops template report --appName my-app

Authoring templates: the file format, variables, data access tags, permission tiers.
Submitting and tracking ops commands: use a registered template to actually run something.

Tensor9 BYOC

Getting Started

Self-Service Onboarding

How It Works

Deploying

Your Customer's Environment

Service Adapters

Costs

Auto-Customizations

Security

Connectivity & Networking

Observability & Operations

Support

tensor9 CLI

Git Template Sources

A reference layout

Registering a source

Conflict resolution

Resyncing against HEAD

Applying the diff: upgrade

Scoping with `--only` and `--actions`

What “retire-here” means

Inventory

Retiring a source

End-to-end example

​A reference layout

​Registering a source

​Conflict resolution

​Resyncing against HEAD

​Applying the diff: upgrade

​Scoping with --only and --actions

​What “retire-here” means

​Inventory

​Retiring a source

​End-to-end example

​Related

A reference layout

Registering a source

Conflict resolution

Resyncing against HEAD

Applying the diff: upgrade

Scoping with `--only` and `--actions`

What “retire-here” means

Inventory

Retiring a source

End-to-end example

Related