Dashboards YAML Reference#

This document is the reference of the Dashboard YAML grammar used for defining dashboards in Semaphore 2.0.

A Semaphore 2.0 Dashboard is a place where you can define widgets in order to overview the operations that take place under the current Semaphore 2.0 organization.

More specifically, a widget is used for watching the activity of pipelines and workflows according to certain criteria that are defined using filters that can help you narrow down the displayed information.

Each dashboard is associated to a given organization. Therefore, in order to view a specific dashboard you should be connected to the organization the dashboard belongs to.

Properties#

This section will present all the properties of the Dashboard YAML grammar except the widgets property and the properties that exist under the widgets property, which are presented in the widgets section.

apiVersion#

The apiVersion property specifies the API version of the Dashboard YAML grammar that will be used in the current document. Different API versions might have different features.

The list of valid values for apiVersion: v1alpha.

kind#

The kind property defines the purpose of the YAML file. For a YAML file that will be used for defining a Dashboard, the value of the kind property should be Dashboard.

The list of valid values for kind: Dashboard.

metadata#

The metadata property defines the metadata of the Dashboard YAML file. The list of supported properties includes name, title, id, create_time and update_time but this might change in future versions.

name in metadata#

The name property holds the name of the dashboard as it will appear in the URL of the dashboard and should be unique among the dashboards of an organization.

The value of value should contain lowercase letters, dashes and numbers only.

title in metadata#

The title property holds the title of the Dashboard as it will appear in the UI of Semaphore 2.0 and it can contain Unicode characters.

id#

The value of the id property is automatically generated and assigned by Semaphore 2.0 and is unique among all dashboards. It should not be edited.

create_time#

The value of the create_time property is automatically generated by Semaphore 2.0 and is in the UNIX epoch format. It holds the time of creation of the dashboard.

update_time#

The value of the update_time property is automatically generated by Semaphore 2.0 and is in the UNIX epoch format. This value is automatically updated each time you make changes to a dashboard.

spec#

The spec property is currently used for holding the widgets property.

Widgets#

The widgets property holds the list of widgets of a dashboard. Each widget defines the actual information that will be displayed on Semaphore 2.0 UI using the name, type and filters properties.

The filters property#

The filters property holds a list of items that can help you filter the output to match certain criteria.

name in widgets#

The name property used in each list item of the widgets property defines the name of the widget as it will appear on the UI of Semaphore 2.0.

type#

The value of type defines whether you want your widget to display information about pipelines or workflows.

The list of valid values for type: list_workflows and list_pipelines.

Workflows list#

In order to create a workflows list you will need to use list_workflows as the value of the type property. A workflows list displays information about workflows.

The supported properties in filters for a workflows list are the following:

  • project_id (optional): allows to display workflows from a given Semaphore 2.0 project. You can find the project ID of an existing Semaphore 2.0 project using the sem get project <name> command.

  • branch (optional): The branch property allows you to filter the widget output by the branch name of the GitHub repository of a Semaphore 2.0 project. Note that the value of the branch property should be an exact match and that there is currently no support for regular expressions in the branch property.

  • github_uid (optional): The github_uid property allows you to display workflows that were initiated by a specific GitHub user. The value of github_uid should correspond to the numeric ID of the user account on GitHub for which we want to list workflows. The value can be found by visiting the following URL https://api.github.com/users/USERNAME and replacing USERNAME with an actual GitHub username. There is a special value for the github_uid property, which is '{{github_uid}}', that is automatically expanded to the GitHub user ID of the user that is visiting the page.

If you are using a list_worflows type and you have no filters, the value of filters should be filters: {}.

Workflows example#

apiVersion: v1alpha
kind: Dashboard
metadata:
  name: my-dashboard
  title: My Dashboard
  id: eb0cc2c7-bbc9-41e4-9e3d-2eb622a673fb
  create_time: "1537888191"
  update_time: "1537889560"
spec:
  widgets:
  - name: Master branch from all projects
    type: list_workflows
    filters:
      branch: master
  - name: All projects on the current organization
    type: list_workflows
    filters: {}

Pipelines list#

In order to create a pipelines list you will need to use list_pipelines as the value of the type property. A pipelines list displays information about pipelines.

The supported properties in filters for a pipelines list are the following:

  • project_id (required): restricts the widget output to pipelines from a single Semaphore 2.0 project. You can find the project ID of an existing Semaphore 2.0 project using the sem get project <name> command.

  • branch (optional): The branch property allows you to filter the widget output by the specified branch name of the GitHub repository of the Semaphore 2.0 project. Note that the value of the branch property should be an exact match and that there is currently no support for regular expressions in the branch property.

  • pipeline_file (optional): the pipeline_file property allows you to filter the generated output using the filename of the pipeline file that is being executed. Please note that the pipeline_file value should not be just the name of the pipeline file but the full path starting from the root directory of the GitHub repository. Therefore, the filename of the default pipeline is .semaphore/semaphore.yml.

Pipelines example#

apiVersion: v1alpha
kind: Dashboard
metadata:
  name: my-dashboard
  title: My Dashboard
  id: eb0cc2c7-bbc9-41e4-9e3d-2eb622a673fb
  create_time: "1537445699"
  update_time: "1537445713"
spec:
  widgets:
  - name: Pipelines
    type: list_pipelines
    filters:
      project_id: 7384612f-e22f-4710-9f0f-5dcce85ba44b
      branch: demo
      pipeline_file: .semaphore/p1.yml
  - name: docs project pipelines
    type: list_pipelines
    filters:
      project_id: 0dd982e8-32f5-4037-983e-4de01ac7fb1e

See also#