Sources & Catalog

A Source says where your code lives. It is the one building block every deployment needs, and every component fetches what it deploys from a source.

Source

A Source is the "where the bytes live" primitive. It is a fetch location, nothing more:

a type, the protocol used to retrieve bytes
a URL
optional credentials for private locations

Source type	Fetches from
`git`	a Git repository
`helm`	a Helm chart repository
`oci`	an OCI registry
`http`	a plain HTTP(S) endpoint
`terraform`	a Terraform module registry

A source describes retrieval, not execution. The same git source can back a Terraform deployment, a Helm deployment, or a raw manifest deployment. What turns bytes into a deployment is the engine, which is declared one layer down on the Catalog Item.

admiral source create \
  --name acme-infra \
  --type git \
  --url https://github.com/acme/infrastructure.git

Open Sources and click New source.
Enter a name (for example, acme-infra).
Choose a type (git) and enter the repository URL.
For a private source, attach a Credential.
Click Create.

Private sources reference a Credential to authenticate when Admiral fetches from them.

Credentials

A Credential is a stored, encrypted secret that a private Source references so Admiral can authenticate when it fetches. It is a first-class resource, so the secret lives in one place and is referenced rather than pasted inline. Credentials are used only by Sources.

Credentials are typed by the authentication mechanism, not the provider:

Type	Holds	Used for
`SSH_KEY`	a private key (and optional passphrase)	a private Git source over SSH
`BASIC_AUTH`	a username and password	a private Helm or HTTP source
`BEARER_TOKEN`	a token	an OCI registry or token-authenticated endpoint

The mechanism has to match how the source authenticates, and Admiral enforces the pairing when you attach a credential:

Source type	Accepts
`git`	SSH key, basic auth
`terraform`	bearer token
`helm`	basic auth, bearer token
`oci`	basic auth, bearer token
`http`	basic auth, bearer token

Secrets are encrypted at rest with envelope encryption (AES-256-GCM); the plaintext is never stored, and is decrypted only to authenticate a fetch.

Credentials let Admiral reach your private source material, such as a Terraform module in a private Git repo or a Helm chart in a private OCI registry, so it can pull that material in and process it into deployable artifacts. They are never used to deploy. A Credential stays bound to Admiral and is not shipped out to an agent.

Catalog Item

A Catalog Item is a reusable template. It points into a source (pinning a ref and a subpath) and declares the engine used to deploy it.

Engine	Deploys	Runs via
`terraform`	infrastructure	Terraform agent
`helm`	a Helm release	Kubernetes agent
`kustomize`	a Kustomize overlay	Kubernetes agent
`manifest`	raw Kubernetes manifests	Kubernetes agent

The source's type constrains which engines are valid; the Catalog Item picks one. A Catalog Item is a starting point, not a parent: it is a template you copy from, never a live runtime dependency.

admiral catalog add \
  --name postgres-rds \
  --source acme-infra \
  --engine terraform \
  --path modules/rds

Open Catalog and click Add item.
Enter a name (for example, postgres-rds).
Choose the source (acme-infra) and an engine (terraform).
Set the path within the source (for example, modules/rds).
Click Add.

One global catalog

There is a single, global catalog. Every Catalog Item in it is discoverable by any application. There is no per-application or per-environment catalog tier.

This is deliberate. A catalog is only valuable if it is curated, and the way you keep it from becoming a junk drawer is curation metadata on the items rather than a structural fork into many catalogs. The intent is for team standards to be expressed as facets you filter on (owner, labels) within the one catalog, not as separate catalogs.

The catalog is optional

A Catalog Item is only a starting point: it prefills a new Component when you create one. You can stand up an entire application without ever touching the catalog, because a Component can be authored inline or copied from another environment (see promotion). The catalog exists to make the common case fast, not to gate it.

Copy, not link. When you add a Catalog Item to an environment, its definition is copied into a Component. There is no live link back, and the Component keeps no reference to the item it came from. Patching a Catalog Item never changes anything already placed. This trades automatic central updates for zero blast radius and self-contained environments, and that trade is intentional.

How they relate

The Source and Catalog Item are the reusable, shared half of the model. Everything below them (the Component and its Revisions) is owned by a specific environment and is the subject of the Applications & Components page.