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:

• DynamicAxis (dynamic), requires the Jenkins DynamicAxis Plugin

• GroovyAxis (groovy), requires the Jenkins GroovyAxis Plugin

• YamlAxis (yaml), requires the Jenkins Yaml Axis Plugin

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

class project_matrix.Matrix(registry)

sequence = 0

The sequence number for the module. Modules are invoked in the order of their sequence number in order to produce consistently ordered XML output.