Matrix ProjectΒΆ

The matrix project module handles creating Jenkins matrix projects. To create a matrix project specify matrix in the project-type attribute to the Job definition. Currently it supports four axes which share the same internal YAML structure:

  • label expressions (label-expression)
  • user-defined values (user-defined)
  • slave name or label (slave)
  • JDK name (jdk)

Requires the Jenkins Matrix Project Plugin.

The module also supports additional, plugin-defined axes:

To tie the parent job to a specific node, you should use node parameter. On a matrix project, this will tie only the parent job. To restrict axes jobs, you can define a single value slave axis.

Job Parameters:

Note

You can only pick one of the strategies.

  • execution-strategy (optional, built in Jenkins):
    • combination-filter (str): axes selection filter
    • sequential (bool): run builds sequentially (default false)
    • touchstone (optional):
      • expr (str) – selection filter for the touchstone build
      • result (str) – required result of the job: stable (default) or unstable
  • yaml-strategy (optional, requires Yaml Axis Plugin):

    • exclude-key (str) – top key containing exclusion rules
    • Either one of:
    • filename (str) – Yaml file containing exclusions
    • text (str) – Inlined Yaml. Should be literal text: | exclude:...
  • axes (list):
    • axis:
      • type (str) – axis type, must be either type defined by Matrix Project Plugin (label-expression, user-defined, slave or jdk) or a type defined by a plugin (see top of this document for a list of supported plugins).
      • name (str) – name of the axis
      • values (list) – values of the axis

The module supports also ShiningPanda axes:

Example:

name: matrix-test003
project-type: matrix
axes:
    - axis:
        type: python
        values:
        - python-2.6
        - python-2.7
        - python-3.4
    - axis:
        type: tox
        values:
        - py26
        - py27
        - py34

Requires the Jenkins ShiningPanda Plugin.

Example:

- job:
    name: matrix-test
    project-type: matrix
    execution-strategy:
      combination-filter: |
        !(os=="fedora11" && arch=="amd64")
      sequential: true
      touchstone:
        expr: 'os == "fedora11"'
        result: unstable
    axes:
      - axis:
         type: label-expression
         name: os
         values:
          - ubuntu12.04
          - fedora11
      - axis:
         type: label-expression
         name: arch
         values:
          - amd64
          - i386
      - axis:
         type: slave
         name: nodes
         values:
          - node1
          - node2
      - axis:
         type: dynamic
         name: config
         values:
          - config_list
      - axis:
         type: user-defined
         name: database
         values:
          - mysql
          - postgresql
          - sqlite
      - axis:
         type: groovy
         name: foo
         command: return [one,two,three]
    builders:
      - shell: make && make check

Examples for yaml axis:

name: matrix-with-yaml-axis
project-type: matrix
axes:
    - axis:
        type: yaml
        filename: config.yaml
        name: python
    - axis:
        type: yaml
        filename: config.yaml
        name: database
name: matrix-with-yaml-strategy-and-exclude-in-file
project-type: matrix
yaml-strategy:
    exclude-key: 'exclude'
    filename: 'exclude.yaml'
axes:
    - axis:
        type: yaml
        filename: 'config.yaml'
        name: python
    - axis:
        type: yaml
        filename: 'config.yaml'
        name: database
name: matrix-with-yaml-strategy-and-inlined-exclude
project-type: matrix
yaml-strategy:
    exclude-key: 'exclude'
    text: |
        exclude:
            - database: postgre
              python: py27
            - python: py35
              database: mysql
axes:
    - axis:
        type: yaml
        filename: config.yaml
        name: python
    - axis:
        type: yaml
        filename: config.yaml
        name: database