--- title: "Sources & Catalog" canonical: "https://admiral.io/docs/concepts/sources-and-catalog" description: "A Source tells Admiral where your code lives - git, Helm, OCI, HTTP, or Terraform - and Catalog Items are reusable templates that point at a source." --- # 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 [#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. ### CLI ```bash admiral source create \ --name acme-infra \ --type git \ --url https://github.com/acme/infrastructure.git ``` ### Web 1. Open **Sources** and click **New source**. 2. Enter a **name** (for example, `acme-infra`). 3. Choose a **type** (`git`) and enter the repository **URL**. 4. For a private source, attach a **Credential**. 5. Click **Create**. Private sources reference a **Credential** to authenticate when Admiral fetches from them. ## Credentials [#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. > **Note:** 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 [#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. ### CLI ```bash admiral catalog add \ --name postgres-rds \ --source acme-infra \ --engine terraform \ --path modules/rds ``` ### Web 1. Open **Catalog** and click **Add item**. 2. Enter a **name** (for example, `postgres-rds`). 3. Choose the **source** (`acme-infra`) and an **engine** (`terraform`). 4. Set the **path** within the source (for example, `modules/rds`). 5. Click **Add**. ### One global catalog [#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 [#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](https://admiral.io/docs/concepts/changesets-and-runs.md#promotion)). The catalog exists to make the common case fast, not to gate it. > **Note:** **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 [#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](https://admiral.io/docs/concepts/applications-and-components.md) page.