Placeholders

Placeholders are template variables that get replaced with actual values during image builds. They enable dynamic configuration based on the current version and metadata.

Overview

Placeholders use the {{placeholder}} syntax and are replaced during the metadata resolution phase. They’re commonly used in:

Docker image tags
Image names
Build arguments
Labels

Available Placeholders

Version Placeholders

string

Full version from the variant configuration.Example: 11.3, 0.4.2, abc1234

"tags": ["type=raw,value={{version}}"]

Results in: 11.3, 0.4.2, etc.

string

Major version number (semver).Example: 11.3.5 → 11

"tags": ["type=raw,value={{major}}"]

Only available for versions with valid semver format (e.g., 1.2.3). Not available for SHA-based versions.

string

Minor version number (semver).Example: 11.3.5 → 3

"tags": ["type=raw,value={{major}}.{{minor}}"]

string

Patch version number (semver).Example: 11.3.5 → 5

"tags": ["type=raw,value={{major}}.{{minor}}.{{patch}}"]

Commit Placeholders

string

Short commit SHA (7 characters).Example: e4b5388

"tags": ["type=raw,value=dev-{{sha}}"]

Results in: dev-e4b5388

string

Full commit SHA (40 characters).Example: e4b53880af4026b8be6a870ae7d8133f744a6181

"buildArgs": {
  "COMMIT": "{{fullSha}}"
}

App Metadata

string

App name from meta.json.Example: cobalt, icones

"images": ["myuser/{{name}}"]

Results in: myuser/cobalt

Usage Examples

Docker Tags

{
  "docker": {
    "tags": [
      "type=raw,value=latest",
      "type=raw,value={{version}}",
      "type=raw,value={{major}}.{{minor}}",
      "type=raw,value={{major}}"
    ]
  }
}

Image Names

{
  "docker": {
    "images": [
      "dockerhub-user/{{name}}",
      "ghcr.io/github-org/{{name}}",
      "registry.example.com/{{name}}"
    ]
  }
}

For app name cobalt, this generates:

dockerhub-user/cobalt
ghcr.io/github-org/cobalt
registry.example.com/cobalt

Build Arguments

{
  "docker": {
    "buildArgs": {
      "VERSION": "{{version}}",
      "COMMIT_SHA": "{{fullSha}}",
      "RELEASE_TAG": "v{{major}}.{{minor}}"
    }
  }
}

Use in Dockerfile:

ARG VERSION
ARG COMMIT_SHA
ARG RELEASE_TAG

LABEL version="${VERSION}" \
      commit="${COMMIT_SHA}" \
      release="${RELEASE_TAG}"

RUN echo "Building version ${VERSION} from ${COMMIT_SHA}"

Labels

{
  "docker": {
    "labels": {
      "app.version": "{{version}}",
      "app.commit": "{{sha}}",
      "app.name": "{{name}}"
    }
  }
}

Complete Examples

Stable Release with Semver

apps/cobalt/meta.json

{
  "name": "cobalt",
  "variants": {
    "latest": {
      "version": "11.3",
      "sha": "e4b53880af4026b8be6a870ae7d8133f744a6181",
      "checkver": {
        "type": "version",
        "repo": "imputnet/cobalt",
        "file": "web/package.json"
      },
      "docker": {
        "images": [
          "myuser/{{name}}"
        ],
        "tags": [
          "type=raw,value=latest",
          "type=raw,value={{version}}",
          "type=raw,value={{major}}"
        ]
      }
    }
  }
}

Generated tags:

myuser/cobalt:latest
myuser/cobalt:11.3
myuser/cobalt:11

Development Build with SHA

apps/cobalt/meta.json

{
  "name": "cobalt",
  "variants": {
    "dev": {
      "version": "8d9bccc",
      "sha": "8d9bccc4fedabb6842fab71bd14e805f1ea21336",
      "checkver": {
        "type": "sha",
        "repo": "imputnet/cobalt",
        "path": "web"
      },
      "docker": {
        "images": [
          "myuser/{{name}}"
        ],
        "tags": [
          "type=raw,value=dev",
          "type=raw,value=dev-{{sha}}"
        ]
      }
    }
  }
}

Generated tags:

myuser/cobalt:dev
myuser/cobalt:dev-8d9bccc

Multi-Registry with Full Metadata

apps/myapp/meta.json

{
  "name": "myapp",
  "title": "My Application",
  "description": "An amazing application",
  "variants": {
    "latest": {
      "version": "2.5.3",
      "sha": "abc123def456",
      "checkver": {
        "type": "tag",
        "repo": "owner/repo"
      },
      "docker": {
        "images": [
          "docker.io/user/{{name}}",
          "ghcr.io/user/{{name}}"
        ],
        "tags": [
          "type=raw,value=latest",
          "type=raw,value={{version}}",
          "type=raw,value={{major}}.{{minor}}",
          "type=raw,value={{major}}"
        ],
        "buildArgs": {
          "APP_VERSION": "{{version}}",
          "GIT_COMMIT": "{{fullSha}}"
        },
        "labels": {
          "version": "{{version}}",
          "commit": "{{sha}}"
        }
      }
    }
  }
}

Generated configuration: Images and tags:

docker.io/user/myapp:latest
docker.io/user/myapp:2.5.3
docker.io/user/myapp:2.5
docker.io/user/myapp:2
ghcr.io/user/myapp:latest
ghcr.io/user/myapp:2.5.3
ghcr.io/user/myapp:2.5
ghcr.io/user/myapp:2

Build args:

APP_VERSION=2.5.3
GIT_COMMIT=abc123def456

Labels:

version=2.5.3
commit=abc123d

Placeholder Resolution

Placeholders are resolved in this order:

App metadata ({{name}}) - from meta.json
Version info ({{version}}, {{sha}}, {{fullSha}}) - from variant config
Semver parts ({{major}}, {{minor}}, {{patch}}) - parsed from version

Version Parsing

Version strings are parsed with loose semver matching:

"11.3"     → { major: "11", minor: "3",  patch: "0" }
"2.5.7"    → { major: "2",  minor: "5",  patch: "7" }
"v1.0.0"   → { major: "1",  minor: "0",  patch: "0" }
"abc123"   → { major: undefined, minor: undefined, patch: undefined }

SHA-based versions (like abc123) don’t have semver parts, so {{major}}, {{minor}}, and {{patch}} will be empty.

Alternative Syntax

Placeholders support multiple bracket styles:

{{placeholder}} - Recommended (double curly braces)
{placeholder} - Single curly braces
$placeholder$ - Dollar signs

All three are equivalent:

"tags": [
  "type=raw,value={{version}}",
  "type=raw,value={version}",
  "type=raw,value=$version$"
]

For consistency, stick to the {{placeholder}} syntax throughout your configuration.

Escaping Placeholders

To use literal placeholder text without replacement, escape with backslashes:

"tags": [
  "type=raw,value=\\{\\{version\\}\\}"
]

Results in literal tag: {{version}}

Best Practices

Use semantic versioning when possible:

"tags": [
  "type=raw,value={{major}}.{{minor}}.{{patch}}",
  "type=raw,value={{major}}.{{minor}}",
  "type=raw,value={{major}}"
]

Include SHA for development builds:

"tags": [
  "type=raw,value=dev-{{sha}}",
  "type=raw,value={{version}}"
]

Use descriptive build arguments:

"buildArgs": {
  "VERSION": "{{version}}",
  "BUILD_COMMIT": "{{fullSha}}"
}

Add version labels:

"labels": {
  "version": "{{version}}",
  "commit": "{{sha}}"
}

Keep image names simple:
```
"images": ["user/{{name}}"]
```

Docker Configuration - Docker build options
Meta Schema - Complete configuration reference
Checkver Types - Version checking strategies

Meta Schema

Actions

Overview

Available Placeholders

Version Placeholders

Commit Placeholders

App Metadata

Usage Examples

Docker Tags

Image Names

Build Arguments

Labels

Complete Examples

Stable Release with Semver

Development Build with SHA

Multi-Registry with Full Metadata

Placeholder Resolution

Version Parsing

Alternative Syntax

Escaping Placeholders

Best Practices

Build docs developers (and LLMs) love

Meta Schema

Actions

​Overview

​Available Placeholders

​Version Placeholders

​Commit Placeholders

​App Metadata

​Usage Examples

​Docker Tags

​Image Names

​Build Arguments

​Labels

​Complete Examples

​Stable Release with Semver

​Development Build with SHA

​Multi-Registry with Full Metadata

​Placeholder Resolution

​Version Parsing

​Alternative Syntax

​Escaping Placeholders

​Best Practices

​Related

Build docs developers (and LLMs) love

Overview

Available Placeholders

Version Placeholders

Commit Placeholders

App Metadata

Usage Examples

Docker Tags

Image Names

Build Arguments

Labels

Complete Examples

Stable Release with Semver

Development Build with SHA

Multi-Registry with Full Metadata

Placeholder Resolution

Version Parsing

Alternative Syntax

Escaping Placeholders

Best Practices

Related