@codedependant/semantic-release-docker 4.2.0 → 4.4.0

package/CHANGELOG.md

@@ -1,5 +1,20 @@
 # Semantic Release Docker
 
+# [4.4.0](https://github.com/esatterwhite/semantic-release-docker/compare/v4.3.0...v4.4.0) (2023-07-11)
+
+
+### Features
+
+* **image**: add support for cache-from build flag [efae32d](https://github.com/esatterwhite/semantic-release-docker/commit/efae32d760bc0ef1978ad97f834b4cb034199ace) - Eric Satterwhite, closes: [#35](https://github.com/esatterwhite/semantic-release-docker/issues/35)
+* **image**: support arbitrary build flags [d7e875d](https://github.com/esatterwhite/semantic-release-docker/commit/d7e875d2b0b8de58e57c56e9ba24bf3c2db5df84) - Eric Satterwhite
+
+# [4.3.0](https://github.com/esatterwhite/semantic-release-docker/compare/v4.2.0...v4.3.0) (2022-12-29)
+
+
+### Features
+
+* **config**: add option to disable post publish image removal [0c03cbd](https://github.com/esatterwhite/semantic-release-docker/commit/0c03cbd16bf7aa34cb435e3782492ad294e9bdfd) - Eric Satterwhite, closes: [#28](https://github.com/esatterwhite/semantic-release-docker/issues/28)
+
 # [4.2.0](https://github.com/esatterwhite/semantic-release-docker/compare/v4.1.0...v4.2.0) (2022-12-19)
 
 

package/README.md

@@ -42,19 +42,22 @@ omitted, it is assumed the docker daemon is already authenticated with the targe
 
 ### Options
 
-| Option            | Description                                                                                                                                                            | Default                                                       |
-|-------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------|
-| `dockerTags`      | _Optional_. An array of strings allowing to specify additional tags to apply to the image. Supports templating                                                         | [`latest`, `{{major}}-latest`, `{{version}}`]                 |
-| `dockerImage`     | _Optional_. The name of the image to release.                                                                                                                          | Parsed from package.json `name` property                      |
-| `dockerRegistry`  | _Optional_. The hostname and port used by the the registry in format `hostname[:port]`. Omit the port if the registry uses the default port                            | `null` (dockerhub)                                            |
-| `dockerProject`   | _Optional_. The project or repository name to publish the image to                                                                                                     | For scoped packages, the scope will be used, otherwise `null` |
-| `dockerFile`      | _Optional_. The path, relative to `$PWD` to a Docker file to build the target image with                                                                               | `Dockerfile`                                                  |
-| `dockerContext`   | _Optional_. A path, relative to `$PWD` to use as the build context A                                                                                                   | `.`                                                           |
-| `dockerLogin`     | _Optional_. Set to false it by pass docker login if the docker daemon is already authorized                                                                            | `true`                                                        |
-| `dockerArgs`      | _Optional_. Include additional values for docker's `build-arg`. Supports templating                                                                                    |                                                               |
-| `dockerPublish`   | _Optional_. Automatically push image tags during the publish phase.                                                                                                    | `true`                                                        |
-| `dockerVerifyCmd` | _Optional_. If specified, during the verify stage, the specified command will execute in a container of the build image. If the command errors, the release will fail. | `false`                                                       |
-| `dockerNetwork`   | _Optional_. Specify the Docker network to use while the image is building.                                                                                             | `default`                                                     |
+| Option                 | Description                                                                                                                                                            | Type                                          | Default                                                       |
+|------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------|---------------------------------------------------------------|
+| `dockerTags`           | _Optional_. An array of strings allowing to specify additional tags to apply to the image. Supports templating                                                         | [Array][]<[String][]>                   | [`latest`, `{{major}}-latest`, `{{version}}`]                 |
+| `dockerImage`          | _Optional_. The name of the image to release.                                                                                                                          | [String][]                                    | Parsed from package.json `name` property                      |
+| `dockerRegistry`       | _Optional_. The hostname and port used by the the registry in format `hostname[:port]`. Omit the port if the registry uses the default port                            | [String][]                                    | `null` (dockerhub)                                            |
+| `dockerProject`        | _Optional_. The project or repository name to publish the image to                                                                                                     | [String][]                                    | For scoped packages, the scope will be used, otherwise `null` |
+| `dockerFile`           | _Optional_. The path, relative to `$PWD` to a Docker file to build the target image with                                                                               | [String][]                                    | `Dockerfile`                                                  |
+| `dockerContext`        | _Optional_. A path, relative to `$PWD` to use as the build context A                                                                                                   | [String][]                                    | `.`                                                           |
+| `dockerLogin`          | _Optional_. Set to false it by pass docker login if the docker daemon is already authorized                                                                            | [String][]                                    | `true`                                                        |
+| `dockerArgs`           | _Optional_. Include additional values for docker's `build-arg`. Supports templating                                                                                    | [Object][]                                    |                                                               |
+| `dockerPublish`        | _Optional_. Automatically push image tags during the publish phase.                                                                                                    | [Boolean][]                                   | `true`                                                        |
+| `dockerVerifyCmd`      | _Optional_. If specified, during the verify stage, the specified command will execute in a container of the build image. If the command errors, the release will fail. | [String][]                                    | `false`                                                       |
+| `dockerNetwork`        | _Optional_. Specify the Docker network to use while the image is building.                                                                                             | [String][]                                    | `default`                                                     |
+| `dockerAutoClean`      | _Optional_. If set to true                                                                                                                                             | [Boolean][]                                   | `true`                                                        |
+| `dockerBuildFlags`     | _Optional_. An object containing additional flags to the `docker build` command. Values can be strings or an array of strings                                          | [Object][]                                    | `{}`                                                          |
+| `dockerBuildCacheFrom` | _Optional_. A list of external cache sources. See [--cache-from][]                                                                                                     | [String][] | [Array][]<[String][]> |                                                               |
 
 ### Build Arguments
 
@@ -79,22 +82,22 @@ secrets and other sensitive information
 
 String template will be passed these
 
-| Variable name  | Description                                                        | Type            |
-|----------------|--------------------------------------------------------------------|-----------------|
-| `git_sha`      | The commit SHA of the current release                              | `String`        |
-| `git_tag`      | The git tag of the current release                                 | `String`        |
-| `release_type` | The severity type of the current build (`major`, `minor`, `patch`) | `String`        |
-| `relase_notes` | The release notes blob associated with the release                 | `String`        |
-| `next`         | Semver object representing the next release                        | `Object`        |
-| `previous`     | Semver object representing the previous release                    | `Object`        |
-| `major`        | The major version of the next release                              | `Number`        |
-| `minor`        | The minor version of the next release                              | `Number`        |
-| `patch`        | The patch version of the next release                              | `Number`        |
-| `prerelease`   | The prerelease versions of the next release                        | `Array<Number>` |
-| `env`          | Environment variables that were set at build time                  | `Object`        |
-| `pkg`          | Values parsed from `package.json`                                  | `Object`        |
-| `build`        | A Random build hash representing the current execution context     | `String`        |
-| `now`          | Current timestamp is ISO 8601 format                               | `String`        |
+| Variable name  | Description                                                        | Type                        |
+|----------------|--------------------------------------------------------------------|-----------------------------|
+| `git_sha`      | The commit SHA of the current release                              | [String][]                  |
+| `git_tag`      | The git tag of the current release                                 | [String][]                  |
+| `release_type` | The severity type of the current build (`major`, `minor`, `patch`) | [String][]                  |
+| `relase_notes` | The release notes blob associated with the release                 | [String][]                  |
+| `next`         | Semver object representing the next release                        | [Object][]                  |
+| `previous`     | Semver object representing the previous release                    | [Object][]                  |
+| `major`        | The major version of the next release                              | [Number][]                  |
+| `minor`        | The minor version of the next release                              | [Number][]                  |
+| `patch`        | The patch version of the next release                              | [Number][]                  |
+| `prerelease`   | The prerelease versions of the next release                        | [Array][]&lt;[Number][]&gt; |
+| `env`          | Environment variables that were set at build time                  | [Object][]                  |
+| `pkg`          | Values parsed from `package.json`                                  | [Object][]                  |
+| `build`        | A Random build hash representing the current execution context     | [String][]                  |
+| `now`          | Current timestamp is ISO 8601 format                               | [String][]                  |
 
 ### Template Helpers
 
@@ -116,7 +119,50 @@ The following handlebars template helpers are pre installed
 | `startswith` | returns true if a string starts with another                           | [Boolean][] | <pre lang="hbs">{{#if (starts myvar 'foo')}}{{ othervar }}{{/if}}</pre>                    |
 |    `upper`   | returns the upper cased varient of the input string                    |  [String][] | <pre lang="hbs">{{upper my_var}}</pre>                                                     |
 
+### Build Flags
 
+Using the `dockerBuildFlags` option allows you to pass arbitrary flags to the build command.
+If the standardized options are not sufficient, `dockerBuildFlags` is a perfect workaround
+until first class support can be added. This is considered and advanced feature, and you should
+know what you intend to do before using. There is no validation, and any configuration of the
+docker daemon required is expected to be done before hand. 
+
+Keys found in `dockerBuildFlags` are normalized as command line flags in the following manner:
+
+* If the key does not start with a `-` it will be prepended
+* all occurences of `_` will be re-written as `-`
+* Single letter keys are considered shorthands e.g. `p` becomes `-p`
+* Multi letter keys are considered long form e.g. `foo_bar` becomes `--foo-bar`
+* If the value is an array, the flag is repeated for each occurance
+* A `null` value may be used to omit the value and only inject the flag itself
+
+#### Example
+
+```javascript
+{
+  plugins: [
+    ['@codedependant/semantic-release-docker', {
+      dockerImage: 'my-image',
+      dockerRegistry: 'quay.io',
+      dockerProject: 'codedependant',
+      dockerCacheFrom: 'myname/myapp'
+      dockerBuildFlags: {
+        pull: null
+      , target: 'release'
+      },
+      dockerArgs: {
+        GITHUB_TOKEN: null
+      }
+    }]
+  ]
+}
+```
+
+This configuration, will generate the following build command
+
+```bash
+> docker build --network=default --quiet --tag quay.io/codedependant/my-image:abc123 --cache-from myname/myapp --build-arg GITHUB_TOKEN --pull --target release -f path/to/repo/Dockerfile /path/to/repo
+```
 
 ## Usage
 
@@ -134,8 +180,12 @@ module.exports = {
       dockerFile: 'Dockerfile',
       dockerRegistry: 'quay.io',
       dockerProject: 'codedependant',
+      dockerBuildFlags: {
+        pull: null
+      , target: 'release'
+      },
       dockerArgs: {
-        API_TOKEN: true
+        API_TOKEN: null
       , RELEASE_DATE: new Date().toISOString()
       , RELEASE_VERSION: '{{next.version}}'
       }
@@ -230,3 +280,6 @@ $ openssl req -new -newkey rsa:2048 -days 365 -nodes -x509 -keyout server.key -o
 [Boolean]: https://mdn.io/boolean
 [String]: https://mdn.io/string
 [Array]: https://mdn.io/array
+[Object]: https://mdn.io/object
+[Number]: https://mdn.io/number
+[--cache-from]: https://docs.docker.com/engine/reference/commandline/build/#cache-from

package/index.js

@@ -5,13 +5,21 @@ const dockerPrepare = require('./lib/prepare.js')
 const dockerVerify = require('./lib/verify.js')
 const dockerPublish = require('./lib/publish.js')
 const buildConfig = require('./lib/build-config.js')
+const dockerSuccess = require('./lib/success.js')
+const dockerFail = require('./lib/fail.js')
 const build_id = crypto.randomBytes(10).toString('hex')
 
 module.exports = {
-  prepare
+  buildConfig
+, fail
+, prepare
 , publish
+, success
 , verifyConditions
-, buildConfig
+}
+
+async function fail(config, context) {
+  return dockerFail(await buildConfig(build_id, config, context), context)
 }
 
 async function prepare(config, context) {
@@ -22,7 +30,10 @@ async function publish(config, context) {
   return dockerPublish(await buildConfig(build_id, config, context), context)
 }
 
+async function success(config, context) {
+  return dockerSuccess(await buildConfig(build_id, config, context), context)
+}
+
 async function verifyConditions(config, context) {
   return dockerVerify(await buildConfig(build_id, config, context), context)
 }
-

package/lib/build-config.js

@@ -5,6 +5,7 @@ const readPkg = require('./read-pkg.js')
 const object = require('./lang/object/index.js')
 const array = require('./lang/array/index.js')
 const parsePkgName = require('./parse-pkg-name.js')
+const typeCast = require('./lang/string/typecast.js')
 const PWD = '.'
 
 module.exports = buildConfig
@@ -15,6 +16,8 @@ async function buildConfig(build_id, config, context) {
   , dockerNoCache: nocache = false
   , dockerTags: tags = ['latest', '{{major}}-latest', '{{version}}']
   , dockerArgs: args = {}
+  , dockerBuildFlags: build_flags = {}
+  , dockerBuildCacheFrom: cache_from
   , dockerRegistry: registry = null
   , dockerLogin: login = true
   , dockerImage: image
@@ -22,6 +25,7 @@ async function buildConfig(build_id, config, context) {
   , dockerContext = '.'
   , dockerVerifyCmd: verifycmd = null
   , dockerNetwork: network = 'default'
+  , dockerAutoClean: clean = true
   } = config
 
   let name = null
@@ -38,10 +42,14 @@ async function buildConfig(build_id, config, context) {
   const root = object.get(context, 'options.root')
   const target = path.relative(root || context.cwd, context.cwd) || PWD
   const {nextRelease = {}} = context
+
+  if (cache_from) build_flags.cache_from = array.toArray(cache_from)
+
   return {
     registry
   , dockerfile
   , nocache
+  , build_flags
   , pkg
   , project
   , publish
@@ -64,5 +72,6 @@ async function buildConfig(build_id, config, context) {
   , env: context.env
   , context: dockerContext
   , network: network
+  , clean: typeCast(clean) === true
   }
 }

package/lib/docker/image.js

@@ -26,15 +26,16 @@ class Image {
 
     this.sha = sha
     this.opts = {
-      args: new Map()
-    , registry: registry
-    , project: project
-    , name: name
-    , build_id: build_id
-    , dockerfile: dockerfile
+      build_id: build_id
+    , args: new Map()
     , context: context
     , cwd: cwd
+    , dockerfile: dockerfile
+    , flags: new Map()
+    , name: name
     , network: network
+    , project: project
+    , registry: registry
     }
   }
 
@@ -72,27 +73,66 @@ class Image {
     return this.opts.network
   }
 
-  arg(key, val) {
+  get flags() {
+    const output = []
+
+    for (const [key, value] of this.opts.flags.entries()) {
+      let normalized = key
+      if (!key.startsWith('-')) {
+        normalized = (key.length === 1 ? `-${key}` : `--${key}`)
+          .toLowerCase()
+          .replace(/_/g, '-')
+      }
+
+      if (value === null) {
+        output.push(normalized)
+        continue
+      }
+
+      for (const item of value) {
+        output.push(normalized, item)
+      }
+    }
+
+    return output
+  }
+
+  arg(key, val = null) {
+    if (val === true || val == null) { // eslint-disable-line no-eq-null
+      this.flag('build-arg', key)
+    } else {
+      this.flag('build-arg', `${key}=${val}`)
+    }
     this.opts.args.set(key, val)
     return this
   }
 
-  get build_cmd() {
-    const args = []
-    for (const [name, value] of this.opts.args.entries()) {
-      if (value === true || value == null) { // eslint-disable-line no-eq-null
-        args.push('--build-arg', name)
-      } else {
-        args.push('--build-arg', `${name}=${value}`)
-      }
+  flag(key, val) {
+    if (val === null) {
+      this.opts.flags.set(key, val)
+      return this
+    }
+
+    let value = this.opts.flags.get(key) || []
+
+    if (Array.isArray(val)) {
+      value = value.concat(val)
+    } else {
+      value.push(val)
     }
+
+    this.opts.flags.set(key, value)
+    return this
+  }
+
+  get build_cmd() {
     return [
       'build'
     , `--network=${this.network}`
     , '--quiet'
     , '--tag'
     , this.name
-    , ...args
+    , ...this.flags
     , '-f'
     , this.dockerfile
     , this.context

package/lib/fail.js

@@ -0,0 +1,9 @@
+'use strict'
+
+const postPublish = require('./post-publish.js')
+
+module.exports = fail
+
+function fail(opts, context) {
+  return postPublish(opts, context)
+}

package/lib/lang/string/index.js

@@ -2,4 +2,5 @@
 
 module.exports = {
   template: require('./template.js')
+, typecast: require('./typecast.js')
 }

package/lib/lang/string/typecast.js

@@ -0,0 +1,32 @@
+'use strict'
+
+/**
+ * @module lib/string/typecast
+ * @author Eric Satterwhite
+ **/
+
+module.exports = function typecast(value) {
+  if (value === 'null' || value === null) return null
+  if (value === 'undefined' || value === undefined) return undefined
+  if (value === 'true' || value === true) return true
+  if (value === 'false' || value === false) return false
+  if (value === '' || isNaN(value)) return value
+  if (isFinite(value)) return parseFloat(value)
+  return value
+}
+
+/**
+ * Best effort to cast a string to its native couter part where possible
+ * Supported casts are booleans, numbers, null and undefined
+ * @function module:lib/string/typecast
+ * @param {String} str The string value to typecast
+ * @return {*} The coerced value
+ * @example
+ * typecast('null') // null
+ * @example
+ * typecast('true') // true
+ * @example
+ * typecast('10.01') // 10.01
+ * @example
+ * typecast({}) // {}
+ **/

package/lib/post-publish.js

@@ -0,0 +1,23 @@
+'use strict'
+
+const docker = require('./docker/index.js')
+
+module.exports = postPublish
+
+async function postPublish(opts, context) {
+  const {cwd, logger} = context
+  const image = new docker.Image({
+    registry: opts.registry
+  , project: opts.project
+  , name: opts.name
+  , dockerfile: opts.dockerfile
+  , build_id: opts.build
+  , cwd: cwd
+  , context: opts.context
+  })
+
+  if (!opts.clean) return
+
+  logger.info(`removing images for ${image.repo}`)
+  await image.clean()
+}

package/lib/prepare.js

@@ -20,15 +20,25 @@ async function dockerPrepare(opts, context) {
   , network: opts.network
   })
 
-  const args = {
-    ...opts.args
+  const vars = buildTemplateVars(opts, context)
+
+  function render(item, vars) {
+    if (Array.isArray(item)) {
+      return item.map((element) => {
+        return string.template(element)(vars)
+      })
+    }
+    return string.template(item)(vars)
   }
 
-  const vars = buildTemplateVars(opts, context)
-  for (const [key, value] of Object.entries(args)) {
+  for (const [key, value] of Object.entries(opts.args)) {
     image.arg(key, string.template(value)(vars))
   }
 
+  for (const [key, value] of Object.entries(opts.build_flags)) {
+    image.flag(key, render(value, vars))
+  }
+
   context.logger.info('building image', image.name)
   context.logger.debug('build command: docker %s', image.build_cmd.join(' '))
   await image.build(path.join(cwd, opts.context))

package/lib/publish.js

@@ -28,6 +28,4 @@ async function publish(opts, context) {
     logger.info(`pushing image: ${image.repo} tag: ${tag}`)
     await image.tag(tag, opts.publish)
   }
-
-  await image.clean()
 }

package/lib/success.js

@@ -0,0 +1,9 @@
+'use strict'
+
+const postPublish = require('./post-publish.js')
+
+module.exports = success
+
+function success(opts, context) {
+  return postPublish(opts, context)
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@codedependant/semantic-release-docker",
   "private": false,
-  "version": "4.2.0",
+  "version": "4.4.0",
   "description": "docker package",
   "main": "index.js",
   "files": [