Concepts
Registry
Publish a repository you own, or pull a copy of an artifact you do not. Revisions are content-addressed, and tags are labels on those revisions.
The registry is where a component's bytes live after they are published. An environment does not fetch those bytes again at deploy time. It pins a revision, and that pin is what a changeset reviews.
A registry revision is the published bytes, identified by digest. When a component applies, it records the revision it runs.
Two ways in
Push is for a repository your organization owns. admiral.yaml at the repository root lists the component paths, and an optional name for each path. admiral component publish packs every declared path and pushes it. Publishing the same tree twice yields the same revision, so a pipeline that publishes everything on each push is safe. Admiral does not scan the repository for components, and it does not compute a version number.
Pull is for an artifact your organization does not own: a Helm chart, a Terraform module, a git tree at a ref, or an archive at a URL. Admiral pulls it, stores a copy in your organization's registry, and records where it came from and what the reference resolved to. The console calls this "Add component". The CLI calls it component pull. The copy is named after the artifact unless you name it, and a chart or module version becomes a tag.
A pull is a copy, not a pointer. Nothing in the deploy path fetches the upstream again. A wrapper chart is optional. Values belong on the environment. A wrapper that adds templates of its own, a chart plus a ClusterIssuer for example, is a real component and stays one.
A private pull names the credentials it may use, or comes through a source, whose grant it then uses. Those credentials are an argument of that pull. They are not stored on the component, and a later pull attaches its own.
Tags
A tag is a label on a revision, the way a Docker tag names an image digest.
| Tag | Moves? |
|---|---|
Semver, such as v1.2.0 | No. Set once. |
Floating, such as latest or main | Yes. |
You refer to a revision as NAME:TAG or NAME@DIGEST. A changeset stores the digest it resolved, and it stores the reference you typed beside that digest. What was reviewed is what runs, even if the tag moves later.
Revisions are not deleted. An untagged revision stays, and it stays readable by digest.
A push to a listened branch of a push source publishes the declared components under the branch name and sha-<short>, and a pull request's head under pr-<n>; see Branches & Pull Requests. A pipeline that publishes with the CLI passes its own tags.
Where to go next
Sources
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.
State
Admiral hosts one Terraform state per component in an environment, or a component keeps the backend it already uses.