wp-docker-buildx

Woodpecker CI plugin to build multiarch OCI images with buildx.

Usage

Be aware that the this plugin requires privileged capabilities, otherwise the integrated Docker daemon is not able to start.

steps:
  - name: docker
    image: quay.io/thegeeklab/wp-docker-buildx
    privileged: true
    settings:
      username: octocat
      password: random-secret
      repo: octocat/example
      tags: latest

Parameters

add_host optional list

Additional host:ip mapping.

Default: none

auto_tag optional bool

Generate tag names automatically based on git branch and git tag.

When this feature is enabled and the event type is tag, the plugin will automatically tag the image using the standard semVer convention. For example:

1.0.0 produces docker tags 1, 1.0, 1.0.0
1.0.0-rc.1 produces docker tags 1.0.0-rc.1 When the event type is push and the target branch is your default branch, the plugin will automatically tag the image as latest. All other event types and branches are ignored.

Default: false

auto_tag_suffix optional string

Generate tag names with the given suffix.

Default: none

bip optional string

Allow the docker daemon to bride IP address.

Default: none

build_args optional map

Custom build arguments for the build. Example:

steps:
  - name: Build
    image: quay.io/thegeeklab/wp-docker-buildx
    settings:
      repo: example/repo
      build_args:
        FOO: bar
        API_KEY:
          from_secret: API_KEY

Default: none

build_args_from_env optional list

Forward environment variables to the build as build arguments. If the same key already exists in build_args, it will not be overwritten. Example:

steps:
  - name: Build
    image: quay.io/thegeeklab/wp-docker-buildx
    settings:
      repo: example/repo
      build_args_from_env:
        - CI_COMMIT_SHA

Default: none

buildkit_config optional string

Content of the docker buildkit toml config. Example:

steps:
  - name: Build
    image: quay.io/thegeeklab/wp-docker-buildx
    settings:
      repo: example/repo
      buildkit_config: |
      [registry."registry.local:30081"]
        http = true
        insecure = true

Default: none

cache_from optional list

Images to consider as cache sources. To properly work, commas used in the cache source entries need to be escaped:

steps:
  - name: Build
    image: quay.io/thegeeklab/wp-docker-buildx
    settings:
      repo: example/repo
      cache_from:
        # while using quotes, double-escaping is required
        - "type=registry\\\\,ref=example"
        - 'type=foo\\,ref=bar'

Default: none

cache_to optional string

Cache destination for the build cache.

Default: none

compress optional bool

Enable compression of the build context using gzip.

Default: false

containerfile optional string

Containerfile to use for the image build.

Default: Containerfile

context optional string

Path of the build context.

Default: .

custom_dns optional list

Custom docker daemon dns server.

Default: none

custom_dns_search optional list

Custom docker daemon dns search domain.

Default: none

daemon_off optional bool

Disable the startup of the docker daemon.

Default: false

debug optional bool

Enable verbose debug mode for the docker daemon.

Default: false

dry_run optional bool

Disable docker push.

Default: false

email optional string

Email address for registry authentication.

Default: $DOCKER_EMAIL

experimental optional bool

Enable docker daemon experimental mode.

Default: false

extra_tags optional list

Additional tags to use for the image including registry.

Additional tags can also be loaded from an .extratags file. This function can be used to push images to multiple registries at once. Therefore, it is necessary to use the config flag to provide a configuration file that contains the authentication information for all used registries.

Default: none

insecure optional bool

Allow the docker daemon to use insecure registries.

Default: false

insecure_skip_verify optional bool

Skip SSL verification.

Default: false

ipv6 optional bool

Enable docker daemon IPv6 support.

Default: false

labels optional list

Labels to add to image.

Default: none

log_level optional string

Plugin log level.

Default: info

max_concurrent_uploads optional string

Max concurrent uploads for each push.

By default the Docker daemon will push five layers of an image at a time. If you are on a low bandwidth connection this may cause timeout issues and you may want to lower with this option.

Default: none

mirror optional string

Registry mirror to pull images.

Default: $DOCKER_PLUGIN_MIRROR

mtu optional string

Docker daemon custom MTU setting.

Default: none

named_context optional list

Additional named build contexts (format: name=path).

Default: none

no_cache optional bool

Disable the usage of cached intermediate containers.

Default: false

output optional string

Export action for the build result (format: path or type=TYPE[,KEY=VALUE]).

Default: none

password optional string

Password for registry authentication.

Default: $DOCKER_PASSWORD

platforms optional list

Target platform for build.

Default: none

provenance optional string

Generate provenance attestation for the build (shorthand for --attest=type=provenance).

Default: none

pull_image optional bool

Enforce to pull base image at build time.

Default: true

quiet optional bool

Enable suppression of the build output.

Default: false

registry optional string

Docker registry to authenticate with.

Default: https://index.docker.io/v1/

registry_config optional string

Content of the registry credentials store file.

Default: $DOCKER_REGISTRY_CONFIG

repo optional string

Repository name for the image.

If the image is to be pushed to registries other than the default DockerHub, it is necessary to set repo as fully-qualified name.

Default: none

sbom optional string

Generate SBOM attestation for the build (shorthand for --attest type=sbom).

Default: none

secrets optional list

Exposes secrets to the build. The secrets can be used by the build using RUN --mount=type=secret mount.

steps:
  - name: Build
    image: quay.io/thegeeklab/wp-docker-buildx
    privileged: true
    environment:
      SECURE_TOKEN:
        from_secret: secure_token
    settings:
      secrets:
        # while using quotes, double-escaping is required
        - "id=raw_file_secret\\\\,src=file.txt"
        - 'id=other_raw_file_secret\\,src=other_file.txt'
        - "id=SECRET_TOKEN"

To use secrets from files a host volume is required. This should be used with caution and avoided whenever possible.

Default: none

storage_driver optional string

Docker daemon storage driver.

Default: none

storage_path optional string

Docker daemon storage path.

Default: /var/lib/docker

tags optional list

Repository tags to use for the image.

Tags can also be loaded from a .tags file.

Default: none

target optional string

Build target to use.

Default: none

username optional string

Username for registry authentication.

Default: $DOCKER_USERNAME

Examples

Push to other registries than DockerHub

If the created image is to be pushed to registries other than the default DockerHub, it is necessary to set registry and repo as fully-qualified name.

GHCR:

steps:
  - name: docker
    image: quay.io/thegeeklab/wp-docker-buildx
    privileged: true
    settings:
      registry: ghcr.io
      username: octocat
      password: secret-access-token
      repo: ghcr.io/octocat/example
      tags: latest

AWS ECR:

steps:
  - name: docker
    image: quay.io/thegeeklab/wp-docker-buildx
    privileged: true
    environment:
      AWS_ACCESS_KEY_ID:
        from_secret: aws_access_key_id
      AWS_SECRET_ACCESS_KEY:
        from_secret: aws_secret_access_key
    settings:
      registry: <account_id>.dkr.ecr.<region>.amazonaws.com
      repo: <account_id>.dkr.ecr.<region>.amazonaws.com/octocat/example
      tags: latest

Build

Build the binary with the following command:

make build

Build the container image with the following command:

docker build --file Containerfile.multiarch --tag thegeeklab/wp-docker-buildx .

Test

docker run --rm \
  -e PLUGIN_TAG=latest \
  -e PLUGIN_REPO=octocat/hello-world \
  -e CI_COMMIT_SHA=00000000 \
  -v $(pwd)/testdata:/build:z \
  -w /build \
  --privileged \
  thegeeklab/wp-docker-buildx --dry-run