Metadata syntax for OpenTestFactory orchestrator plugins¶
You can create plugins to perform tasks in your workflows. Plugins require a metadata file that uses YAML syntax.
About YAML syntax for OpenTestFactory orchestrator plugins¶
Plugins require a metadata file. The metadata filename must be plugin.yaml.
The data in the metadata file defines the inputs, outputs and main entrypoint
for your plugin.
Plugin metadata files use YAML syntax. If you’re new to YAML, you can read “Learn YAML in five minutes.”
You can put more than one YAML document in your metadata file. They may all refer to the same plugin.
kind¶
Required The plugin type (ChannelPlugin, ProviderPlugin,
PublicationPlugin, or GeneratorPlugin).
metadata.name¶
Required The name of your plugin.
metadata.author¶
Optional The name of the plugin’s author.
metadata.description¶
Required A short description of the plugin.
cmd¶
Required The shell command used to start the plugin.
events¶
Required for ProviderPlugin and GeneratorPlugin plugins, not present
for other plugin kinds. The event(s) to subscribe to.
Possible entries are category, categoryPrefix, and categoryVersion.
If categoryPrefix is not specified, category is required.
categoryVersion can only be specified if at least the category or
categoryPrefix is specified.
Example¶
This example subscribes to helloworld@v1, helloworld@v2, and helloworld
events, but not to prefix/helloworld@v1.
events:
- category: helloworld
This example subscribes to prefix/foo@v1 and prefix/bar@v2 events, but
not to prefix@v1.
events:
- categoryPrefix: prefix
This example subscribes to prefix/foo@v1 and prefix/bar@v1 events, but
not to prefix/foo@v2.
events:
- categoryPrefix: prefix
categoryVersion: v1
This last example only subscribes to prefix/helloworld@v1 and prefix/helloworld@v2
events.
events:
- categoryPrefix: prefix
category: helloworld
categoryVersion: v1
- categoryPrefix: prefix
category: helloworld
categoryVersion: v2
inputs¶
Optional Input parameters allow you to specify data that the plugin expects to use during runtime. The OpenTestFactory orchestrator stores input parameters as environment variables. Input ids with uppercase letters are converted to lowercase during runtime. We recommended using lowercase input ids.
Example¶
This example configures two inputs: numOctocats and octocatEyeColor.
The numOctocats input is not required and will default to a value of ‘1’. The
octocatEyeColor input is required and has no default value. Workflow files that
use this plugin must use the with keyword to set an input value for
octocatEyeColor. For more information about the with syntax, see “Workflow
syntax for OpenTestFactory orchestrator.”
inputs:
numOctocats:
description: 'Number of Octocats'
required: false
default: '1'
octocatEyeColor:
description: 'Eye color of the Octocats'
required: true
When you specify an input to a plugin in a workflow file or use a default input
value, the orchestrator creates an environment variable for the input with the name
INPUT_<VARIABLE_NAME>. The environment variable created converts input names
to uppercase letters and replaces spaces with _ characters.
For example, if a workflow defined the numOctocats and octocatEyeColor inputs,
the action code could read the values of the inputs using the
INPUT_NUMOCTOCATS and INPUT_OCTOCATEYECOLOR environment variables.
inputs.<input_id>¶
Required A string identifier to associate with the input. The value of
<input_id> is a map of the input’s metadata. The <input_id> must be a
unique identifier within the inputs object. The <input_id> must start with a
letter or _ and contain only alphanumeric characters, -, or _.
inputs.<input_id>.description¶
Required A string description of the input parameter.
inputs.<input_id>.required¶
Required A boolean to indicate whether the plugin requires the input
parameter. Set to true when the parameter is required.
inputs.<input_id>.default¶
Optional A string representing the default value. The default value is
used when an input parameter isn’t specified in a workflow file.
outputs¶
Optional Output parameters allow you to declare data that a plugin sets. Plugins that run later in a workflow can use the output data set in previously run plugins. For example, if you had a plugin that performed the addition of two inputs (x + y = z), the plugin could output the sum (z) for other plugins to use as an input.
If you don’t declare an output in your plugin metadata file, you can still set outputs and use them in a workflow. For more information on setting outputs in a plugin, see “Workflow commands for OpenTestFactory orchestrator.”
Example¶
outputs:
sum: # id of the output
description: 'The sum of the inputs'
outputs.<output_id>¶
Required A string identifier to associate with the output. The value of
<output_id> is a map of the output’s metadata. The <output_id> must be a
unique identifier within the outputs object. The <output_id> must start with
a letter or _ and contain only alphanumeric characters, -, or _.
outputs.<output_id>.description¶
Required A string description of the output parameter.
outputs for composite run steps plugins¶
Optional outputs use the same parameters as outputs.<output_id> and
outputs.<output_id>.description (see “outputs for OpenTestFactory orchestrator plugins”), but
also includes the value token.
Example¶
outputs:
random-number:
description: "Random number"
value: ${{ steps.random-number-generator.outputs.random-id }}
runs:
using: "composite"
steps:
- id: random-number-generator
run: echo "::set-output name=random-id::$(echo $RANDOM)"
shell: bash
outputs.<output_id.value>¶
Required The value that the output parameter will be mapped to. You can set
this to a string or an expression with context. For example, you can use the
steps context to set the value of an output to the output value of a step.
For more information on how to use context and expression syntax, see “Context and expression syntax for OpenTestFactory workflows.”
branding¶
You can use a color and Feather icon to create a badge to personalize and distinguish your plugin. Badges are shown next to your plugin name in the OpenTestFactory Marketplace.
Example¶
branding:
icon: 'award'
color: 'green'
branding.color¶
The background color of the badge. Can be one of: white, yellow, blue,
green, orange, red, purple, or gray-dark.
branding.icon¶
The name of the Feather icon to use.
| activity | airplay | alert-circle | alert-octagon |
| alert-triangle | align-center | align-justify | align-left |
| align-right | anchor | aperture | archive |
| arrow-down-circle | arrow-down-left | arrow-down-right | arrow-down |
| arrow-left-circle | arrow-left | arrow-right-circle | arrow-right |
| arrow-up-circle | arrow-up-left | arrow-up-right | arrow-up |
| at-sign | award | bar-chart-2 | bar-chart |
| battery-charging | battery | bell-off | bell |
| bluetooth | bold | book-open | book |
| bookmark | box | briefcase | calendar |
| camera-off | camera | cast | check-circle |
| check-square | check | chevron-down | chevron-left |
| chevron-right | chevron-up | chevrons-down | chevrons-left |
| chevrons-right | chevrons-up | circle | clipboard |
| clock | cloud-drizzle | cloud-lightning | cloud-off |
| cloud-rain | cloud-snow | cloud | code |
| command | compass | copy | corner-down-left |
| corner-down-right | corner-left-down | corner-left-up | corner-right-down |
| corner-right-up | corner-up-left | corner-up-right | cpu |
| credit-card | crop | crosshair | database |
| delete | disc | dollar-sign | download-cloud |
| download | droplet | edit-2 | edit-3 |
| edit | external-link | eye-off | eye |
| fast-forward | feather | file-minus | |
| file-plus | file-text | file | film |
| filter | flag | folder-minus | folder-plus |
| folder | gift | git-branch | git-commit |
| git-merge | git-pull-request | globe | grid |
| hard-drive | hash | headphones | heart |
| help-circle | home | image | inbox |
| info | italic | layers | layout |
| life-buoy | link-2 | link | list |
| loader | lock | log-in | log-out |
| map-pin | map | maximize-2 | |
| maximize | menu | message-circle | message-square |
| mic-off | mic | minimize-2 | minimize |
| minus-circle | minus-square | minus | monitor |
| moon | more-horizontal | more-vertical | move |
| music | navigation-2 | navigation | octagon |
| package | paperclip | pause-circle | pause |
| percent | phone-call | phone-forwarded | phone-incoming |
| phone-missed | phone-off | phone-outgoing | phone |
| pie-chart | play-circle | play | plus-circle |
| plus-square | plus | power | |
| printer | radio | refresh-ccw | refresh-cw |
| repeat | rewind | rotate-ccw | rotate-cw |
| rss | save | scissors | search |
| send | server | settings | share-2 |
| share | shield-off | shield | shopping-bag |
| shopping-cart | shuffle | sidebar | skip-back |
| skip-forward | slash | sliders | smartphone |
| speaker | square | star | stop-circle |
| sun | sunrise | sunset | tablet |
| tag | target | terminal | thermometer |
| thumbs-down | thumbs-up | toggle-left | toggle-right |
| trash-2 | trash | trending-down | trending-up |
| triangle | truck | tv | type |
| umbrella | underline | unlock | upload-cloud |
| upload | user-check | user-minus | user-plus |
| user-x | user | users | video-off |
| video | voicemail | volume-1 | volume-2 |
| volume-x | volume | watch | wifi-off |
| wifi | wind | x-circle | x-square |
| x | zap-off | zap | zoom-in |
| zoom-out |