Configuration: Workloads

This section describes the workload-config.yaml configuration file. See the configuration overview for further information.

Overview

A workload represents one or more repositories, in one or more repository groups. With this concept, you can model a team, an application or a single component.

You can also group workloads using tags.

Note See the workload concept section.

Examples

Grouping by layer

Here is how you might model a team with frontend and backend repositories:

# a team with 'frontend' and 'backend' repositories

workloads:
  - id: team-athena
    codeManagement:
      type: github
      serverId: example-github
      projectName: athena
      repoGroups:
        backend:
          components:
            - repo: example-api
            - repo: another-api
        frontend:
          components:
            - repo: customer-web
            - repo: admin-web
    codeAnalysis:
      type: sonar
      serverId: example-sonar
    projectManagement:
      type: jira
      serverId: example-jira
      project: ATH

A monorepo example with multiple components, each with its own Sonar mapping.

workloads:
  - id: CodeMetricsMonoRepo
    name: "CodeMetrics"
    codeManagement:
      type: github
      serverId: CodeMetrics
      projectName: code-metrics-user-org
      repoGroups:
        CodeMetricsCore:
          components:
            - repo: /code-metrics/
              name: backend
              paths: ["/backend"]
            - repo: /code-metrics/
              name: frontend
              paths: ["/frontend"]
            - repo: /code-metrics/
              name: ui
              paths: ["/ui"]
        CodeMetricsML:
          components:
            - repo: /code-metrics/
              name: machinelearning
              paths: ["/machinelearning"]
    codeAnalysis:
      type: sonar
      serverId: example-sonar
      mappings:
        - key: ml
          componentName: machinelearning
        - key: code-metrics-frontend
          componentName: frontend
        - key: code-metrics-ui
          componentName: ui
    pipelines:
      type: github
      serverId: CodeMetrics
      projectName: code-metrics-user-org
      jobGroups:
        CodeMetrics:
          jobs:
            - name: code-metrics
    projectManagement:
      type: jira
      serverId: mock-jira
      teamFilterJql: '"Team name[Dropdown]" in ("Gaia")'
      project: DEV
      prodFilterJql: '"Project Environment[Dropdown]" = PROD'

Note Repository group names, such as backend are arbitrary. You can name these groups whatever you like.

Excluding specific pipeline jobs

You can exclude specific jobs from a job group using the jobs format with the exclude flag. This is useful when you want to include all jobs except certain ones, without having to list every job individually.

workloads:
  - id: team-athena
    # ...
    pipelines:
      type: github
      serverId: example-github
      projectName: athena
      jobGroups:
        all:
          jobs:
            # include all jobs matching a regex
            - name: /.+/
            # exclude a specific job by name
            - name: Dependabot Updates
              exclude: true

Note Job entries support exact strings and regular expressions (wrapped in slashes, e.g. /Dependabot.*/).

Referencing a repo group in pipeline job specs

Instead of specifying job names individually, you can reference a repo group defined in codeManagement using fromRepoGroup. This causes the repo names in that group to be used as job name patterns, keeping pipeline and repo configuration in sync automatically.

workloads:
  - id: athena
    codeManagement:
      type: github
      serverId: foo
      repoGroups:
        backend:
          components:
            - repo: api1
            - repo: api2
    pipelines:
      type: jenkins
      serverId: example
      jobGroups:
        backend:
          jobs:
            - fromRepoGroup: backend

fromRepoGroup also supports exclude: true to exclude the repos in a group:

jobGroups:
  all:
    jobs:
      # include everything
      - name: /.+/
      # then exclude any job that matches a repo in the 'bots' group
      - fromRepoGroup: bots
        exclude: true

Note Each jobs entry must specify at least one of name, fromRepoGroup, repo, or componentName. fromRepoGroup is mutually exclusive with repo and componentName.

Scoping job groups to specific repositories

You can scope a job group to a specific repository using repo or componentName instead of fromRepoGroup. This is useful when a job group should target a single known repository, without needing to define a full repo group.

Using repo — specify the repository name directly:

jobGroups:
  backend:
    jobs:
      - repo: my-api
      - repo: my-worker

Using componentName — look up the repository by the component name defined in codeManagement.repoGroups:

workloads:
  - id: athena
    codeManagement:
      type: github
      serverId: foo
      repoGroups:
        backend:
          components:
            - name: api
              repo: my-api
    pipelines:
      type: github
      serverId: foo
      jobGroups:
        backend:
          jobs:
            # resolves to the repo whose component name is 'api'
            - componentName: api

Both repo and componentName support exclude: true.

Behaviour by pipeline provider

Provider	Effect of repo / componentName
GitHub	Scopes which repositories are scanned for workflows. An optional name field filters which workflow names to include within those repos.
Azure DevOps	Used as a job name pattern (since ADO job names are repository names).
Jenkins	Used as a job name pattern matched against pipeline display names.
Dynatrace	Used as a job name pattern matched against metric dimension values.
CodePipeline	Used as a job name pattern matched against pipeline names.

For GitHub, combining repo with a name filter allows targeting a specific workflow within a repository:

jobGroups:
  backend:
    jobs:
      # fetch only the 'CI' workflow from 'my-api'
      - repo: my-api
        name: CI

Here is how you might recreate the previous configuration, by using regular expressions to match repository names:

# a team with 'frontend' and 'backend' repositories, matched using regular expressions

workloads:
  - id: team-athena
    codeManagement:
      type: github
      serverId: example-github
      projectName: athena
      repoGroups:
        # match all repositories that end in '-api' using a regular expression
        backend:
          components:
            - repo: "/.*-api/"
        # match all repositories that end in '-web' using a regular expression
        frontend:
          components:
            - repo: "/.*-web/"
    codeAnalysis:
      type: sonar
      serverId: example-sonar
    projectManagement:
      type: jira
      serverId: example-jira
      project: ATH

Here is how you might recreate the previous configuration, by using Sonar tags to look up repository names:

# a team with 'frontend' and 'backend' repositories, looked up via tags in Sonar

workloads:
  - id: team-athena
    codeManagement:
      type: github
      serverId: example-github
      projectName: athena
      repoGroups:
        # determine the backend repos based on their tags in Sonar
        backend:
          sonarTags:
            - "be"
        # determine the frontend repos based on their tags in Sonar
        frontend:
          sonarTags:
            - "fe"
    codeAnalysis:
      type: sonar
      serverId: example-sonar
    projectManagement:
      type: jira
      serverId: example-jira
      project: ATH

Grouping by application

Here is how you might model a team with multiple applications:

# a team with multiple applications

workloads:
  - id: team-hera
    codeManagement:
      type: github
      serverId: example-github
      projectName: hera
      repoGroups:
        account-app:
          components:
            - repo: accounts-web
            - repo: accounts-api
            - repo: accounts-infra
        sales-app:
          components:
            - repo: sales-portal
            - repo: sales-api
            - repo: sales-platform
    codeAnalysis:
      type: sonar
      serverId: example-sonar
    projectManagement:
      type: jira
      serverId: example-jira
      project: HER

Repository and Sonar mappings

When CodeMetrics looks up quality metrics about a repository, the query to Sonar uses the repository name as the component 'key' parameter by default.

It is possible to specify a different key for a given repository using the mappings property within the codeAnalysis section of a workload.

workloads:
  - id: example-workload
    # ... other config ...
    codeAnalysis:
      type: sonar
      serverId: example-sonar
      mappings:
        - key: petclinic
          componentName: spring-petclinic

In this example, CodeMetrics would use the Sonar component key petclinic for the repository named spring-petclinic.

You can also map by VCS repository name:

workloads:
  - id: example-workload
    codeAnalysis:
      type: sonar
      serverId: example-sonar
      mappings:
        - key: my-sonar-project
          vcsRepoName: my-repo

Deployment configuration

To model deployments for a workload, you can reference a deployment configuration by its ID.

workloads:
  - id: team-athena
    # ...
    # other workload configuration
    # ...
    deployment:
      deploymentId: my-deployments

In this example, the workload team-athena references the deployment configuration my-deployments.

To learn more about deployments, see the deployment configuration section.

Quality gates configuration

To attach quality gates to a workload, reference a quality gates configuration by its ID and version.

workloads:
  - id: team-athena
    # ...
    # other workload configuration
    # ...
    qualityGates:
      id: default
      version: 0.1.0

In this example, the workload team-athena references the quality gates configuration with ID default at version 0.1.0.

See the quality gates configuration section for the full schema and examples.