Declare artifacts and tooling

For feature teams. This page explains two lists that you write once for the whole file: artifacts and tooling. Neither list is part of an environment.

Artifacts

An artifact is something that your build produces, for example a jar or a container image. A deployment names an artifact by its id. Choose where your service runs explains deployments.

Field	Required	Format	Meaning
`id`	Yes	An id, unique in the file	The name that a deployment uses.
`type`	Yes	A type of your platform	The kind of artifact.
`spec`	Yes	A map	The settings of the artifact. The `type` decides which settings it needs.

An artifact has no enabled field. Two artifacts can have the same type. For example, a build that makes two jars declares two entries of type jar, each with its own id.

A jar

A jar artifact has one setting, the path of the built archive:

artifacts:
  - id: shop-jar
    type: jar
    spec:
      path: target/shop.jar

A container image

A container-image artifact has two settings. The dockerfile is the path of the Dockerfile in your project. The registry is the place where the built image is published.

artifacts:
  - id: shop-image
    type: container-image
    spec:
      dockerfile: Dockerfile
      registry: registry.example.com/finance/container-shop

An OpenAPI document for Kong

A kong-oas artifact has one setting, the path of the OpenAPI document that describes your API. A kong-api deployment uses it.

  - id: partner-api-oas
    type: kong-oas
    spec:
      path: src/main/resources/openapi/partner-api.yaml

Each path is text. Joomiz does not check that a file exists at that path.

Tooling

An entry in tooling configures one tool for your service.

Field	Required	Format	Meaning
`id`	Yes	An id, unique in the file	Your name for the entry.
`type`	Yes	A type of your platform, unique in the file	The tool.
`enabled`	No	`true` or `false`	Whether the tool is on. The default is `true`.
`spec`	Yes	A map	The settings of the tool. The `type` decides which settings it needs.

An application can have only one entry for each tool type. Both the id and the type must be unique in the file.

This is an example with two tools:

tooling:
  - id: renovate
    type: renovate
    enabled: true
    spec:
      schedule: before 6am on monday

  - id: checkmarx
    type: checkmarx
    enabled: true
    spec:
      scan-on: pull-request
      severity-threshold: high

The settings of these two types are:

Type	What it is for	Setting	Allowed values
`renovate`	Automated dependency updates	`schedule`	Text in the schedule syntax of Renovate, at most 256 characters
`checkmarx`	Static application security testing	`scan-on`	`pull-request`, `push` or `schedule`
`checkmarx`	Static application security testing	`severity-threshold`	`low`, `medium`, `high` or `critical`

A setting that the type does not know is an error. This spec is invalid on purpose:

      cron: before 6am on monday

You see:

error: the control plane found 2 problems in joomiz.yaml (checked by https://joomiz.example.com/validate)
  tooling:
    tooling[0].spec: required property 'schedule' not found
    tooling[0].spec: property 'cron' is not defined in the schema and the schema does not allow additional properties

Add a tool with the CLI

The command joomiz tooling add adds an entry to the end of tooling in your file. It creates the section when the file has none. It does not contact the control plane.

joomiz tooling add --id checkmarx --type checkmarx --spec scan-on=pull-request --spec severity-threshold=high

You see:

Updated joomiz.yaml
  id:       checkmarx
  type:     checkmarx
  enabled:  true
  spec.scan-on: pull-request
  spec.severity-threshold: high
note: the tool type is not checked here. "joomiz validate" checks it against the server.

The first line of your output shows the full path of your file. The command does not check the type. Run joomiz validate to check it. Repeat --spec for each setting. Add --enabled=false to switch the tool off.

Limits

A file has at most 50 entries in artifacts and at most 50 in tooling.
The spec of one entry is at most 16 KB when written as JSON.
A duplicate id in artifacts or in tooling is refused when you register:

error: the control plane rejected joomiz.yaml (HTTP 400)
  Invalid artifacts
  the submitted artifacts is not valid: 2 violations found, listed in this response's 'violations'
  artifacts[0].id: duplicate artifact id 'shop-jar' within this application
  artifacts[1].id: duplicate artifact id 'shop-jar' within this application

joomiz validate does not report a duplicate id in artifacts. Check the list before you register.

A duplicate tool type is refused by validate and by register:

error: the control plane found 2 problems in joomiz.yaml (checked by https://joomiz.example.com/validate)
  tooling:
    tooling[0].type: duplicate tooling type 'renovate' — an application may declare at most one entry per tool type
    tooling[1].type: duplicate tooling type 'renovate' — an application may declare at most one entry per tool type

What registration stores

joomiz register stores both lists, as they are in the file that you register. It checks the structure of each entry, the size of each spec and the duplicate ids.

This is not available yet. You cannot change the stored lists after register. validate and plan read the lists in your file, so a deployment can name an artifact that you added to the file. The stored lists stay as you registered them.

Describe where your service runs in Define your environments.