Pushing & Pulling Images

A complete guide to tagging, pushing, pulling, and managing container images in your DepAegis private registry.

Tagging Images for DepAegis

Before you can push an image, it must be tagged with the DepAegis registry hostname. Docker uses the tag prefix to determine which registry to push to. The format is:

<registry-host>/<org>/<image>:<tag>

Tag an existing local image:

# Tag for DepAegis
docker tag my-app:latest app.depaegis.com/my-org/my-app:latest

# Tag with a specific version
docker tag my-app:v1.2.0 app.depaegis.com/my-org/my-app:1.2.0

The <org> segment in the tag maps to a DepAegis organization. You must have write permissions in that organization to push images.

Pushing Images

Once the image is tagged, push it to DepAegis:

docker push app.depaegis.com/my-org/my-app:1.2.0

Docker uploads each layer. If a layer already exists in the registry (deduplication), the upload is skipped. DepAegis automatically triggers a vulnerability scan and SBOM generation after the push completes.

Pushing all tags

If you have multiple tags for the same image, push them individually or use --all-tags:

docker push --all-tags app.depaegis.com/my-org/my-app

DepAegis performs asynchronous scanning after the push returns. Large images may take a minute to appear as "scanned" in the dashboard. The image is still pullable immediately — the scan status updates independently.

Image Tagging Best Practices

A consistent tagging strategy makes images discoverable, traceable, and reproducible. Here are the most common approaches:

Semantic Versioning

Use semver tags for releases. This is the most common strategy for production images:

app.depaegis.com/my-org/my-app:1.2.0
app.depaegis.com/my-org/my-app:1.2.1
app.depaegis.com/my-org/my-app:2.0.0

Git SHA

Tag every build with its git commit SHA for full traceability. This ensures every deployed image can be traced back to an exact source commit:

docker build -t app.depaegis.com/my-org/my-app:sha-a1b2c3d .
docker push app.depaegis.com/my-org/my-app:sha-a1b2c3d

Latest tag

The latest tag is a convenience tag pointing to the most recent build. It is not updated automatically — it is only updated when you explicitly push it:

# Push a versioned tag AND latest together
docker tag my-app app.depaegis.com/my-org/my-app:1.2.0
docker tag my-app app.depaegis.com/my-org/my-app:latest
docker push app.depaegis.com/my-org/my-app:1.2.0
docker push app.depaegis.com/my-org/my-app:latest

Avoid using latest in production deployments. Pinning to an explicit version or SHA prevents accidental breakage from an unexpected image update.

Strategy	Example Tag	Use Case
Semver	`1.2.0`	Release builds
Git SHA	`sha-a1b2c3d`	CI builds, full traceability
Branch name	`main`, `feature-auth`	Development / staging
Latest	`latest`	Convenience only — not for production

Multi-Architecture Manifests

DepAegis supports OCI image manifests and manifest lists (fat manifests), enabling multi-architecture images. Use docker buildx to build and push images for multiple platforms simultaneously:

Create a buildx builder

docker buildx create --name mybuilder --use
docker buildx inspect --bootstrap

Build and push for multiple platforms

docker buildx build \
  --platform linux/amd64,linux/arm64,linux/arm/v7 \
  -t app.depaegis.com/my-org/my-app:1.2.0 \
  --push .

This builds the image for three architectures and pushes a single manifest list to DepAegis. When a user pulls the image, Docker automatically selects the correct variant for their platform:

# On an ARM64 machine — pulls the arm64 variant
docker pull app.depaegis.com/my-org/my-app:1.2.0

You can inspect the manifest list with docker buildx imagetools inspect:

docker buildx imagetools inspect app.depaegis.com/my-org/my-app:1.2.0

Pulling Images

Pulling images from DepAegis works exactly like pulling from any other registry:

docker pull app.depaegis.com/my-org/my-app:1.2.0

If you omit the tag, Docker pulls latest by default:

docker pull app.depaegis.com/my-org/my-app

Pulling and running in one step

docker run --rm app.depaegis.com/my-org/my-app:1.2.0

If the image is not present locally, Docker pulls it first, then runs it.

Pulling by digest

For maximum reproducibility, pull by digest instead of tag. Digests are immutable — they always point to the exact same image data:

docker pull app.depaegis.com/my-org/my-app@sha256:abcdef123456...

Use digest references in production manifests (Kubernetes, Docker Compose) to ensure deployments are immutable and reproducible.

Image Scanning & Security Results

Every image pushed to DepAegis is automatically scanned for known vulnerabilities. Scan results are available in the DepAegis dashboard:

Open Dashboard → Images.
Click on an image repository to see all tags.
Click a tag to view the Vulnerabilities tab — CVEs grouped by severity (Critical, High, Medium, Low).
Click the SBOM tab to see the full CycloneDX Software Bill of Materials.

If your organization has configured a dependency firewall, images that fail the security policy will be blocked from pulling. Administrators can exempt specific images or adjust the policy threshold.

Cleaning Up Old Images

Over time, image repositories accumulate old tags. DepAegis provides several ways to manage image retention:

Via Dashboard

Navigate to Dashboard → Images → [Repository].
Select the tags you want to remove.
Click Delete selected.

Via REST API

# Delete a specific tag
curl -X DELETE \
  -H "Authorization: Bearer $DEPAEGIS_TOKEN" \
  "https://app.depaegis.com/v2/my-org/my-app/manifests/1.0.0"

Image deletion is permanent. Tags deleted from DepAegis cannot be restored. Ensure no running services depend on the tag before deleting it.

Garbage Collection

When you delete a tag or manifest, the layers referenced by that manifest are not immediately removed — other manifests may reference the same layers. DepAegis runs garbage collection (GC) to reclaim disk space by removing unreferenced layers.

Automatic GC

DepAegis runs garbage collection automatically on a configurable schedule (default: nightly). Administrators can configure the schedule in Settings → Registry → Garbage Collection.

Manual GC

Trigger garbage collection immediately via the dashboard or API:

curl -X POST \
  -H "Authorization: Bearer $DEPAEGIS_TOKEN" \
  "https://app.depaegis.com/api/admin/registry/gc"

After deleting many images (e.g. cleaning up old CI builds), trigger a manual GC to reclaim disk space immediately instead of waiting for the nightly run.

← Previous

Configuring Docker

Access Tokens