--- title: "Sources" canonical: "https://admiral.io/docs/concepts/sources" description: "A source is one upstream location with a standing grant: a git repository, a Helm repository, an OCI namespace or a Terraform registry namespace, what it may publish, and whether it publishes on push." --- # Sources A **source** is one upstream location Admiral may read: a git repository, a Helm repository, an OCI registry namespace or a Terraform registry namespace, with the grant that reaches it and a bound on what may come in. An organization's sources are curated by its admins. Importing a component through a source, or publishing one on push, is what the source is for. ## One location, one grant A source has: * a **kind**, the protocol: `git`, `helm`, `oci` or `terraform` * a **location**, the narrowest thing the protocol addresses: one repository, one chart repository, one registry namespace. Never a bare host or a whole GitHub organization. The location is immutable, because a published version records the source it came through. * exactly one **grant**: a [credential](#credentials) the organization holds, or for a GitHub repository, Admiral's GitHub App installed on the account * **allows**, the artifacts or paths that may come in: exact names, or a prefix with a trailing `*`; `*` alone allows everything * a **trigger**: on request, when someone imports through it; or on push, when the GitHub App publishes what the repository declares | Kind | Location | Artifacts are | | ----------- | --------------------------------------------- | ----------------------------------------------------------- | | `git` | `https://github.com/acme/payments` | paths in the repository; versions are its tags and branches | | `helm` | `https://charts.jetstack.io` | charts the repository's index lists | | `oci` | `oci://ghcr.io/argoproj/argo-helm` | names under the namespace | | `terraform` | `registry.opentofu.org/terraform-aws-modules` | `name/provider` under the namespace | Only a git repository reached through the GitHub App can publish on push, and a push source names the branches it listens to. One push source per repository. A source is **ready** while its grant reaches its location. When the App is uninstalled, the repository leaves the installation, or a credential is rotated away, the source **needs attention** and says why; it is fixed in place, never recreated. ## What a source offers A source answers what its upstream offers: a Helm repository or registry namespace lists its artifacts within what the source allows, a container registry takes a name, and a git repository lists its tags and branches. Admiral reads the upstream through a cache and refreshes it on read when it is older than two hours. A read says when the upstream was last read, and after a failure, what it offered before and why the refresh failed. Nothing polls an upstream in the background. ## Importing through a source Adding a component from a source picks the source, then an artifact, then a version exactly as the source lists it. No credential rides the request: picking the source is picking the grant. The version is exact; `latest` on an import is a tag literally named `latest`, never a keyword. A branch is imported at its tip, and the version does not follow it. ```bash admiral component import --from jetstack cert-manager --version v1.16.2 admiral component import --from infra modules/vpc --version v2.1.0 ``` In a terminal, a missing artifact or version is asked from the source's list, with nothing pre-selected. The published version records the source it came through. A component can also be imported by address, without a source, naming the credentials that import may present. See [Registry](https://admiral.io/docs/concepts/registry.md). ## Publishing on push A push source publishes every component its repository's `admiral.yaml` declares when a listened branch is pushed, and plans a pull request's head where its base branch is followed. See [Branches & Pull Requests](https://admiral.io/docs/concepts/branches-and-pull-requests.md). ```yaml # admiral.yaml at the repository root components: - path: modules/payments - path: modules/network_hub name: network-hub ``` A declared path outside what the source allows is refused, component by component; the push goes on. A push source publishes to an existing name only when that name was first published through it. ## Credentials A **credential** is a stored, encrypted secret the organization holds. It is one of a source's two grants, and an import by address may present it. Credentials are typed by mechanism, not by provider: | Type | Holds | Fits | | ------------ | -------------------------------------------- | -------------------------------------------------------- | | SSH key | a private key, and optionally its passphrase | a git repository over SSH | | Basic auth | a username and password | a Helm repository, an OCI registry | | Bearer token | a token | a Helm repository, an OCI registry, a Terraform registry | | GitHub App | an App of your own, its installation and key | a git repository over HTTPS | A credential may name the hosts it is allowed to reach, and it is presented only to those. A fetch that reaches a host no attached credential covers fails naming the host. Secrets are encrypted at rest with envelope encryption, decrypted only to fetch, and never shipped to an agent. A credential or integration a source names cannot be deleted while the source exists. ## Where to go next * [Registry](https://admiral.io/docs/concepts/registry.md): Publish a repository you own, or pull a copy of an artifact you do not * [Branches & Pull Requests](https://admiral.io/docs/concepts/branches-and-pull-requests.md): How a push plans and a review applies