--- title: "Replication Rules" description: "What a replication rule does: which events trigger it, how layer flattening changes the destination path, and what happens to namespaces and failed tasks." date: 2026-08-13 lastmod: 2026-08-19 canonical: "https://container-registry.com/docs/2.15/administration-manual/replication/replication-rules/" source: "https://container-registry.com/docs/2.15/administration-manual/replication/replication-rules/index.md" harbor_version: "2.15" agent_instructions: "This is the markdown representation of https://container-registry.com/docs/2.15/administration-manual/replication/replication-rules/index.md. Prefer this version over scraping the HTML. The site index is at https://container-registry.com/llms.txt." --- > Agent-friendly representation of . Site index: . # Replication Rules *What a replication rule does: which events trigger it, how layer flattening changes the destination path, and what happens to namespaces and failed tasks.* Replication Rules ================================= Replication rules specify which artifacts will be moved between registries and how they should be moved. Each replication rule includes: * a filter to catch particular artifacts; * a scheduler; * a flattening rule. To create or run one, see [Manage Replication Rules](/docs/2.15/administration-manual/replication/manage-replication-rules/index.md). ## Which Events Trigger a Replication or Not The following events will trigger a replication that is set to be event-based: * a new artifact has been pushed into the resource registry; * an artifact was re-tagged in the resource registry; * optionally: an artifact has been deleted from the resource registry; to activate this one, you need to tick the checkbox near *Delete remote resources when locally deleted*. ![](../img/replicate_deleted.png) > **Note:** Changes in the artifact labels do not count as events and never trigger a replication. ## Flattening Docker images have multiple layers that reflect all changes you've done to the original image. Layers are organized into hierarchies. When a layer in the hierarchy is changed, Docker will propagate the changes to all the layers below this one. The hierarchy may have more than one brunch. Consequently, you need to make sure that you keep track of where certain layers come from, which changes were applied to them, and how to find the "original" layer. You can also choose not to track this information if you do not need it. An image hierarchy can be visualized in your command line tool using the tool known as [dockviz](https://github.com/justone/dockviz) and looks like this: ```terminal $ dockviz images -t -l └─511136ea3c5a Virtual Size: 0.0 B ├─f10ebce2c0e1 Virtual Size: 103.7 MB │ └─74fe38d11401 Virtual Size: 209.6 MB Tags: ubuntu:12.04, ubuntu:precise ├─ef519c9ee91a Virtual Size: 100.9 MB │ └─a7cf8ae4e998 Virtual Size: 171.3 MB Tags: ubuntu:12.10, ubuntu:quantal │ ├─5c0d04fba9df Virtual Size: 513.7 MB Tags: nate/mongodb:latest │ └─f832a63e87a4 Virtual Size: 243.6 MB Tags: redis:latest └─02dae1c13f51 Virtual Size: 98.3 MB └─316b678ddf48 Virtual Size: 169.4 MB Tags: ubuntu:13.04, ubuntu:raring ``` In your repository, this hierarchy is represented through slashes in the artifact name. The highest level appears in the image name **on the left**, before the very first slash. By selecting a flattening rule, you keep some or all or none of the hierarchy levels. It is pretty much like removing parts of the image name. When you drop – flatten – one or a few levels, one or a few slashes and characters between them will be removed from the artifact name. > **Note:** Chartmuseum always needs two levels left on the chart name. Options for the scope of flattening: * **Flatten All Levels** will remove the complete hierarchy leaving only the tag of the last layer; * **No Flatteing** will keep the hierarchy as it appears in the resource registry; Other options always **remove a number of levels** (parts of the image name starting from the **left**): * Flattening 1 level; * Flattening 2 levels; * Flattening 3 levels. ## Pattern Matching Rules for the Name and Tag Resource Filter You can use double-starred patterns as explained [here](/docs/2.15/user-manual/double-starred-patterns/index.md) to include only certain repositories in the project or certain tags. The pattern will be matched with the names of repositories or artifacts. In addition to that, you can use two more pattern matching methods. 1. Contrary to double-starred patterns that take any match independently of the number of the characters that can be added to the pattern to build a match, with the **question mark**, you can specify that only one character can be added. For instance, `test?` will be matched with `test1` and `test2` but not with `test12`. 2. To enter **more than one pattern** as a match, create a list of them using **curly brackets** and separating single patterns with simple commas. You can use *?* and asterisk in the patterns inside the list. ## Replication Tasks ### Failed Tasks Replication tasks are running replications. Failed replication tasks undergo a few execution attempts automatically. ### Reasons for Replication Task Failure Most of the time, two reasons for the replication task failure are possible: * network issues; * insufficient user rights in the destination registry. ## Namespace Match With the Destination Registry When you push artifacts to a registry using replication, you do not need to create the namespace – project and repository – in the destination registry before. Exactly as in the case of pushing images to Container Registry from your local machine, the repository will be created in the destination. It also plays no role if the destination is your Container Registry system or an external one. ### Exception In [Quay.io](https://quay.io) you need to create namespaces in advance before using the endpoint.