onestic/docker-ci repository overview

⁠Docker CI

⁠Overview

This image, onestic/docker-ci, is designed to facilitate consistent linting, building, and pushing Docker images (and their README files) across projects.

It's been optimized for seamless integration into Bitbucket Pipelines, ensuring reliable and standardized Docker image management process.

⁠Supported platforms and tags

This image is built for linux/amd64 and linux/arm64 platforms.

The only supported tag for this image is based and limited to the major Docker version they are based on: 25-cli. This tag will be updated daily. New features may be added, always in a retro compatible way, using feature flags if needed for their activation.

Note: There may be other development-related tags, use at your own discretion.

⁠Features summary

• Inherited: All features already provided by the latest official Docker 25 CLI image⁠.
• Up-to-date: Built daily from the latest Docker 25 CLI base image available.
• Linting: Provides linting capabilities to ensure Dockerfile adherence to best practices and standards.
• Automatic login to registry: Allow login to registry when container starts, by using predefined environment variables.
• Multiplatform builds: Create multiplatform builds by using buildx⁠ and QEMU⁠ emulators, using predefined environment variables.
• Pushing: Streamlines the process of pushing Docker images to container registries.
• Pushing README to specified Docker / container registry, in order to keep image description and reference documentation updated.
• Bitbucket pipe: Similar to GitHub actions, it is ready to be used as a Bitbucket pipe⁠. Perform a set of actions in a consistent way across projects (linting => multiplatform building => image tagging => pushing).
• Customizable: Actions, behaviour and more are configurable using environment variables⁠ (see The Twelve Factor App - III. Config⁠).

⁠Behaviour

When started with arguments, containers based on this image will behave as a regular docker:25-cli container. It is possible to run this image this way, but it does not offer any advantage compared to its base image.

The intended way to use this image is without arguments, configured using environment variables⁠. When used this way (pipe mode), it will attempt to execute the following actions:

1. Lint Dockerfile for errors / bad practices, using hadolint⁠. Hadolint configuration is stored internally, so it can be applied the same way to all Dockerfile files.
2. Login to specified Docker / container registry, using specified credentials, for pulling / pushing images.
3. Build images multiplatform, and optionally push them, tagging them in a consistent way based on the VCS / CI information available (automatic OCI labels⁠ coming soon, see also this link⁠).
4. Push README to registry. This action will attempt to push README-containers.md / README.md file to specified Docker / container registry, in order to keep image description and reference documentation updated.

⁠Usage

⁠Bitbucket - Pipe mode

Sample usage (with short variables description) in Bitbucket pipelines as a pipe (remove commented lines that you don't need):

pipelines:
  default:
    - step:
        name: 'Lint, build & push'
        script:
          - pipe: 'docker://onestic/docker-ci:25-cli'
            variables:
              # Uncomment lines below to skip pipe actions.
              # DOCKER_CI_LINT_SKIP: '1'
              # DOCKER_CI_LOGIN_SKIP: '1'
              # DOCKER_CI_BUILD_SKIP: '1'
              # DOCKER_CI_PUSHRM_SKIP: '1'
              # Uncomment and adapt line below to specify a workdir different from default. You usually won't need this.
              # DOCKER_CI_WORKDIR: ${BITBUCKET_CLONE_DIR}
              # Uncomment and adapt line below to specify custom path to Dockerfile. You won't need it unless Dockerfile is not at the repository root.
              # DOCKER_CI_DOCKERFILE: ${BITBUCKET_CLONE_DIR}/Dockerfile
              # Uncomment line below to increment shell verbosity (-x).
              # DOCKER_CI_DEBUG: '1'
              # Uncomment and adapt line below to log in to a different registry (other than Docker Hub).
              # DOCKER_CI_LOGIN_REGISTRY: docker.io
              # Declare and set login values as secure variables within Bitbucket system.
              DOCKER_CI_LOGIN_REGISTRY_USER: ${DOCKER_CI_LOGIN_REGISTRY_USER}
              DOCKER_CI_LOGIN_REGISTRY_PASSWORD: ${DOCKER_CI_LOGIN_REGISTRY_PASSWORD}
              # Uncomment and adapt line below to tag / push image to a different registry (other than Docker Hub).
              # DOCKER_CI_BUILD_IMAGE_REGISTRY: docker.io
              # Uncomment and adapt line below to tag / push image for a different registry user (other than onestic).
              # DOCKER_CI_BUILD_IMAGE_USER: 'onestic'
              # Uncomment and adapt line below to tag / push image for a different registry repository (other than repository slug).
              # DOCKER_CI_BUILD_IMAGE_REPOSITORY: ${BITBUCKET_REPO_SLUG}
              # Uncomment and adapt line below to specify platforms to build against, when they differ from defaults.
              # DOCKER_CI_BUILD_PLATFORM_EMULATORS: 'linux/amd64,linux/arm64'
              # If build context is the repository root itself, and not the context folder, uncomment line below.
              # DOCKER_CI_BUILD_CONTEXT: ${BITBUCKET_CLONE_DIR}
              # Uncomment and use line below to specify Dockerfile build args if needed.
              # DOCKER_CI_BUILD_ARGS: ''
              # Uncomment and adapt line below if you need to fine tune `docker buildx build` command arguments.
              # DOCKER_CI_BUILD_COMMAND_ARGS: '--push'
              # Use line below to specify additional image tags (within target registry, user and repository).
              # DOCKER_CI_BUILD_TAGS: ''
              # The rest of lines are used for automatic tagging.
              # You can override then or set them empty on purpose if you want to skip some type of automatic tags.
              # DOCKER_CI_BUILD_NUMBER: ''
              # DOCKER_CI_BUILD_TAG: ''
              # DOCKER_CI_BUILD_PR_ID: ''
              # DOCKER_CI_BUILD_BRANCH: ''

⁠Manually / One-shot mode

It is possible to run this image in one-shot mode, for example for linting, as long as you define action variables, mount volumes and define working directory properly.

For example, if you cd into a project where there is a Dockerfile, you could lint the Dockerfile this way:

docker run --rm -it \
  -e DOCKER_CI_LOGIN_SKIP=1 \
  -e DOCKER_CI_BUILD_SKIP=1 \
  -e DOCKER_CI_PUSHRM_SKIP=1 \
  -w /opt/project \
  -v "$(pwd):/opt/project" \
  -- \
  onestic/docker-ci:25-cli 

The previous will:

• Instruct container to skip login and build steps, so only lint is executed.
• Prepare working directory and mount required data in it, having a Dockerfile at its roots (it works because of variables defaults).

Following the previous example, it is possible to execute any combination of pipe actions manually / locally in one-shot mode.

⁠Variables reference

⁠Disabling specific pipe actions

Each pipe action can be skipped by setting its own skip environment variables to 1:

⁠Configuring pipe actions

⁠Common variables

⁠Action: Dockerfile lint

Please note that mandatory variables are only mandatory when action is not skipped.

⁠Action: Registry login

Please note that mandatory variables are only mandatory when action is not skipped.

⁠Action: Build / push

Please note that mandatory variables are only mandatory when action is not skipped.

The following table shows action specific variables:

⁠Action: Push README

Please note that mandatory variables are only mandatory when action is not skipped.

Also note that pushing README files over 25k characters to Docker Hub may fail.

The following table shows action specific variables: