Skip to main content
Version: Cloud (SaaS)

Dashboards YAML

This page describes the YAML syntax used to define dashboards in Semaphore.

Overview​

A dashboard in an interface containing widgets. Widgets can give you an overview of events and operations that happen in your Semaphore organization.

More specifically, widgets are used for viewing the activity of pipelines and workflows. You can use filters to modify the views.

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

apiVersion​

The apiVersion property

Specifies the API version of the Dashboard YAML syntax.

The only possible value is: v1alpha

kind​

Defines the type of resource to create.

For dashboards use the value: Dashboard

metadata​

Defines metadata about the dashboard.

It contains the following properties:

name​

This property describes the name of the dashboard. The name of the dashboard is part of the URL and should be unique among an organization's dashboards.

The value should only contain alphanumeric characters and dashes.

title​

This property describes the title of the dashboard as it appears on the Semaphore website. It can only contain Unicode characters.

id​

This is the unique ID for the dashboard and is automatically generated by Semaphore.

create_time​

The dashboard creation time in UNIX epoch format.

update_time​

The dashboard's last config update time is in UNIX epoch format.

spec​

Specifies the dashboard elements. Contains only one property: widgets.

widgets​

This property is a list of widgets for the dashboard.

Each item list contains the following elements:

name​

This property describes the name of the widget to be shown in the dashboard on the Semaphore website.

type​

Defines the type of widget to display. The widget can show either pipelines or workflows.

Possible values for this property are:

  • list_workflow
  • list_pipelines

filters​

Describes the criteria to filter elements shown in the widget.

The properties contained in depend on the widget type.

See the properties for each type below:

If you don't want to apply filters, use the following snippet:

filters: {}

list_workflows​

When type: list_workflows the widget shows the workflow activity.

In this scenario, you may use the following properties inside filters to filter the activity shown in the widget:

  • project_id (optional): show only workflows for the specified project
  • branch (optional): shows only workflows for the specified branch for a given project (exact string match supported only)
Example for list_workflows
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: {}

list_pipelines​

When type: list_pipelines the widget shows the pipeline activity.

In this scenario, you may use the following properties inside filters to filter the activity shown in the widget:

  • project_id (required): select the project to show pipeline activity
  • branch (optional): shows only workflows for the specified branch for a given project (exact string match supported only)
  • pipeline_file (optional): filter pipelines by pipeline file name. Requires full path to the pipeline file.
Example for list_pipelines
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​