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 thebranch
property should be an exact match and that there is currently no support for regular expressions in thebranch
property.
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 thebranch
property should be an exact match and that there is currently no support for regular expressions in thebranch
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 thepipeline_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