Breakwater / Docs
Request early access

Repositories

Repositories are where your Docker images live. They correspond to Docker registry repositories and contain the actual container images that customers pull.

What is a Repository?

A repository in Breakwater maps directly to a Docker registry repository. When you push an image like:

registry.breakwaterapp.com/acme/webapp:v1.0

The repository name is webapp, and it belongs to the vendor acme.

Creating a Repository

  1. Navigate to Repositories in the vendor portal
  2. Click New Repository
  3. Enter the repository details:
    • Name (required): The repository name
    • Products: Select which products this repository belongs to
  4. Click Create Repository

Repository Names

Repository names must follow Docker naming conventions:

  • Start with a lowercase letter or number
  • Contain only lowercase letters, numbers, dots (.), underscores (_), hyphens (-), and slashes (/)
  • Use slashes to separate segments (each segment must start with a lowercase letter or number)
  • Be unique within your vendor account

Valid examples:
- webapp
- my-app
- myapp_enterprise
- app.v2
- platform/api
- team/tools/webapp

Invalid examples:
- MyApp (uppercase not allowed)
- -webapp (can't start with hyphen)
- my app (spaces not allowed)
- webapp//api (empty segment)

Full Image Path

The complete path to pull or push an image is:

registry.breakwaterapp.com/{vendor-slug}/{repository-name}:{tag}

For example, if your vendor slug is acme and your repository is webapp:

registry.breakwaterapp.com/acme/webapp:latest
registry.breakwaterapp.com/acme/webapp:v1.0.0

Linking to Products

Repositories must be linked to at least one product for customers to access them through licenses. When creating or editing a repository, you can select multiple products.

How access works:

  1. A customer has a license for "Product A"
  2. "Product A" is linked to the webapp repository
  3. The customer can pull images from webapp (subject to license dates and tag patterns)

A repository can belong to multiple products. This is useful when:

  • Multiple product editions share common components
  • You want to grant access to the same images through different licensing tiers

Managing Repositories

Viewing Repositories

The Repositories page lists all your repositories with:

  • Repository name
  • Full image path
  • Linked products

Click on a repository to see:

  • Repository details
  • Linked products
  • Recent pull history for this repository

Editing Repositories

  1. Click on the repository to view details
  2. Click Edit
  3. Update the linked products
  4. Click Update Repository

Note: You cannot change the repository name after creation, as this would break existing image references.

Deleting Repositories

  1. Click on the repository to view details
  2. Click Delete
  3. Confirm the deletion

Deleting a repository removes it from all linked products. Customers will no longer be able to pull images from this repository. Existing images in the registry are not affected.

Pushing Images

Use a vendor auth token to push images to your repositories:

# Log in with your vendor token
docker login registry.breakwaterapp.com -u vtok_xxxxx

# Tag your local image
docker tag myapp:latest registry.breakwaterapp.com/acme/webapp:v1.0.0

# Push to the registry
docker push registry.breakwaterapp.com/acme/webapp:v1.0.0

See Auth Tokens for details on creating vendor tokens.

Best Practices

Repository Organization

  • One repository per image: Each distinct container image should have its own repository
  • Consistent naming: Use a consistent naming scheme across repositories
  • Separate concerns: Don't mix unrelated images in the same repository

Tagging Strategy

Choose a tagging strategy that works with tag patterns:

  • Semantic versioning: v1.0.0, v1.0.1, v2.0.0
  • Date-based: 2026.01, 2026.02
  • Named tags: stable, latest, lts

Consider how customers will want to pin to specific versions or receive updates.

Multiple Products, Shared Repositories

If multiple products share the same base images, you can:

  1. Create separate repositories for shared and product-specific images
  2. Link shared repositories to all relevant products
  3. Use tag patterns on licenses to differentiate access levels