Dashboards YAML Reference#

This document shows you how to use the Dashboard YAML grammar to define dashboards in Semaphore 2.0.

A Semaphore 2.0 Dashboard is an interface where you can define widgets, which you can use to overview the operations that take place in a Semaphore 2.0 organization.

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

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

Properties#

This section will present all the properties of the Dashboard YAML grammar, except the widgets property and the properties that are subordinate to it, 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.

Here is a list of valid values for the apiVersion property: v1alpha.

kind#

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

Here is a list of valid values for the kind property: Dashboard.

metadata#

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

name in metadata#

The name property holds the name of a dashboard as it appears in the URL of the dashboard, and should be unique among an organization's dashboards.

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

title in metadata#

The title property holds the title of the Dashboard as it appears in Semaphore 2.0's UI and can contain Unicode characters.

id#

The value of the id property is automatically generated and assigned by Semaphore 2.0 and is unique for each dashboard. 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 that a dashboard was created.

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 a change to a dashboard.

spec#

The spec property is used to hold the widgets property.

Widgets#

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

The filters property#

The filters property holds a list of items that can help you filter 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 appears in the UI of Semaphore 2.0.

type#

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

Here is a list of valid values for the type property: list_workflows and list_pipelines.

Workflows list#

In order to create a workflows list you 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 as follows:

  • project_id (optional): allows the display of 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 widget output by branch name (of the repository) for 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.

If you are using the 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 widget output by specified branch name of a repository for 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 generated output using the filename of a 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 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#