> ## Documentation Index
> Fetch the complete documentation index at: https://tally.wharflab.com/llms.txt
> Use this file to discover all available pages before exploring further.

# tally/labels/no-buildx-git-overlap

> Dockerfile labels should not duplicate git provenance labels generated by Buildx.

Dockerfile labels should not duplicate git provenance labels generated by
Buildx.

| Property | Value                                                                        |
| -------- | ---------------------------------------------------------------------------- |
| Severity | Warning                                                                      |
| Category | Correctness                                                                  |
| Default  | Enabled, models `BUILDX_GIT_LABELS=full`                                     |
| Auto-fix | Suggestion, when `org.opencontainers.image.revision` can be mapped precisely |

## Description

Buildx can generate image labels from the current git checkout when
`BUILDX_GIT_LABELS` is enabled. Manually maintaining the same keys in the
Dockerfile can leave stale source, revision, or Dockerfile-path metadata on the
image.

`org.opencontainers.image.revision` means the source control revision of the
packaged content. A Dockerfile cannot know that value reliably unless the build
system injects it for the exact checkout being built. When Buildx is already
configured to generate the revision label, the Dockerfile label is redundant at
best and stale at worst.

This rule checks labels that affect the exported image. Labels in throwaway
builder stages are ignored unless the final image inherits from that stage.

## Buildx modes

| Mode                                                                              | Generated labels checked                                                  |
| --------------------------------------------------------------------------------- | ------------------------------------------------------------------------- |
| `off`, `none`, or `strconv.ParseBool` false values such as `false`, `0`, `f`, `F` | Disabled                                                                  |
| `strconv.ParseBool` true values such as `true`, `1`, `t`, `T`                     | `org.opencontainers.image.revision`, `com.docker.image.source.entrypoint` |
| `full`                                                                            | The `true` labels plus `org.opencontainers.image.source`                  |

## Examples

### Bad

```dockerfile theme={null}
FROM alpine:3.20

LABEL org.opencontainers.image.revision="${VCS_REF}"
LABEL org.opencontainers.image.source="https://github.com/example/app" \
      com.docker.image.source.entrypoint="Dockerfile"
```

### Good

```dockerfile theme={null}
FROM alpine:3.20

LABEL org.opencontainers.image.title="app" \
      org.opencontainers.image.description="Example application"
```

Let Buildx attach git-derived labels at build time:

```bash theme={null}
BUILDX_GIT_LABELS=full docker buildx build .
```

## Fixes

For `LABEL org.opencontainers.image.revision=...`, Tally offers two
suggestion-level fixes when the source pair can be mapped precisely:

* comment out the instruction, preserving the original text for review
* delete the instruction or pair

When `org.opencontainers.image.revision` appears inside a grouped `LABEL`,
Tally removes only that key/value pair and preserves the unrelated labels. The
comment-out fix inserts a commented standalone `LABEL` before the grouped
instruction, then removes the active pair from the group.

Fixes are scoped to the exported image's stage chain. If a final stage shadows
an inherited `org.opencontainers.image.revision`, the suggested fix also removes
the inherited copy so applying the fix once does not reveal the same issue
again. Builder-only stages outside the exported chain are still ignored.

`org.opencontainers.image.source` and
`com.docker.image.source.entrypoint` are reported but not auto-fixed by this
rule; they may be intentional static project metadata in some build workflows.

## Configuration

Tally does not infer builder configuration from its own process environment.
By default, this rule models `BUILDX_GIT_LABELS=full` because the diagnostics
are informational and help keep git-derived metadata owned by the build system.
Configure the mode explicitly when the repository uses a narrower Buildx git
label policy. Boolean string values are parsed like Docker/Buildx documents
`BUILDX_GIT_LABELS` parsing: `true`, `1`, `t`, and `T` all select the narrower
non-`full` generated-label set.

```toml theme={null}
[rules.tally.labels.no-buildx-git-overlap]
buildx-git-labels = "full"
```

Disable the rule when Dockerfile labels intentionally own these keys:

```toml theme={null}
[rules.tally.labels.no-buildx-git-overlap]
buildx-git-labels = "off"
```

## References

* [Docker Build variables: `BUILDX_GIT_LABELS`](https://docs.docker.com/build/building/variables/#buildx_git_labels)
* [Docker Buildx 0.10.0 release notes](https://github.com/docker/buildx/releases/tag/v0.10.0)
* [Docker object labels](https://docs.docker.com/engine/manage-resources/labels/)
* [OCI image annotations](https://github.com/opencontainers/image-spec/blob/main/annotations.md)

## Related Rules

* [`tally/labels/no-stale-base-digest`](/rules/tally/labels/no-stale-base-digest)
* [`tally/labels/no-duplicate-keys`](/rules/tally/labels/no-duplicate-keys)
* [`tally/labels/valid-key`](/rules/tally/labels/valid-key)