backstage

1
{
2
  "$schema": "http://json-schema.org/draft-07/schema",
3
  "$id": "TemplateV1beta3",
4
  "description": "A Template describes a scaffolding task for use with the Scaffolder. It describes the required parameters as well as a series of steps that will be taken to execute the scaffolding task.",
5
  "examples": [
6
    {
7
      "apiVersion": "scaffolder.backstage.io/v1beta3",
8
      "kind": "Template",
9
      "metadata": {
10
        "name": "react-ssr-template",
11
        "title": "React SSR Template",
12
        "description": "Next.js application skeleton for creating isomorphic web applications.",
13
        "tags": ["recommended", "react"]
14
      },
15
      "spec": {
16
        "owner": "artist-relations-team",
17
        "type": "website",
18
        "parameters": {
19
          "required": ["name", "description", "repoUrl"],
20
          "backstage:permissions": {
21
            "tags": ["one", "two"]
22
          },
23
          "properties": {
24
            "name": {
25
              "title": "Name",
26
              "type": "string",
27
              "description": "Unique name of the component"
28
            },
29
            "description": {
30
              "title": "Description",
31
              "type": "string",
32
              "description": "Description of the component"
33
            },
34
            "repoUrl": {
35
              "title": "Pick a repository",
36
              "type": "string",
37
              "ui:field": "RepoUrlPicker"
38
            }
39
          }
40
        },
41
        "steps": [
42
          {
43
            "id": "fetch",
44
            "name": "Fetch",
45
            "action": "fetch:plain",
46
            "parameters": {
47
              "url": "./template"
48
            },
49
            "backstage:permissions": {
50
              "tags": ["one", "two"]
51
            }
52
          },
53
          {
54
            "id": "publish",
55
            "name": "Publish to GitHub",
56
            "action": "publish:github",
57
            "parameters": {
58
              "repoUrl": "${{ parameters.repoUrl }}"
59
            },
60
            "if": "${{ parameters.repoUrl }}"
61
          }
62
        ],
63
        "output": {
64
          "catalogInfoUrl": "${{ steps.publish.output.catalogInfoUrl }}"
65
        }
66
      }
67
    }
68
  ],
69
  "allOf": [
70
    {
71
      "$ref": "Entity"
72
    },
73
    {
74
      "type": "object",
75
      "required": ["spec"],
76
      "properties": {
77
        "apiVersion": {
78
          "enum": ["scaffolder.backstage.io/v1beta3"]
79
        },
80
        "kind": {
81
          "enum": ["Template"]
82
        },
83
        "spec": {
84
          "type": "object",
85
          "required": ["type", "steps"],
86
          "properties": {
87
            "type": {
88
              "type": "string",
89
              "description": "The type of component created by the template. The software catalog accepts any type value, but an organization should take great care to establish a proper taxonomy for these. Tools including Backstage itself may read this field and behave differently depending on its value. For example, a website type component may present tooling in the Backstage interface that is specific to just websites.",
90
              "examples": ["service", "website", "library"],
91
              "minLength": 1
92
            },
93
            "owner": {
94
              "type": "string",
95
              "description": "The user (or group) owner of the template",
96
              "minLength": 1
97
            },
98
            "parameters": {
99
              "oneOf": [
100
                {
101
                  "type": "object",
102
                  "description": "The JSONSchema describing the inputs for the template.",
103
                  "properties": {
104
                    "backstage:permissions": {
105
                      "type": "object",
106
                      "description": "Object used for authorizing the parameter",
107
                      "properties": {
108
                        "tags": {
109
                          "type": "array",
110
                          "items": {
111
                            "type": "string"
112
                          }
113
                        }
114
                      }
115
                    }
116
                  }
117
                },
118
                {
119
                  "type": "array",
120
                  "description": "A list of separate forms to collect parameters.",
121
                  "items": {
122
                    "type": "object",
123
                    "description": "The JSONSchema describing the inputs for the template.",
124
                    "properties": {
125
                      "backstage:permissions": {
126
                        "type": "object",
127
                        "description": "Object used for authorizing the parameter",
128
                        "properties": {
129
                          "tags": {
130
                            "type": "array",
131
                            "items": {
132
                              "type": "string"
133
                            }
134
                          }
135
                        }
136
                      }
137
                    }
138
                  }
139
                }
140
              ]
141
            },
142
            "presentation": {
143
              "type": "object",
144
              "description": "A way to redefine the labels for actionable buttons.",
145
              "properties": {
146
                "backButtonText": {
147
                  "type": "string",
148
                  "description": "A button which return the user to one step back."
149
                },
150
                "createButtonText": {
151
                  "type": "string",
152
                  "description": "A button which start the execution of the template."
153
                },
154
                "reviewButtonText": {
155
                  "type": "string",
156
                  "description": "A button which open the review step to verify the input prior to start the execution."
157
                }
158
              }
159
            },
160
            "EXPERIMENTAL_recovery": {
161
              "type": "object",
162
              "description": "A task recovery section.",
163
              "properties": {
164
                "EXPERIMENTAL_strategy": {
165
                  "type": "string",
166
                  "description": "Recovery strategy for your task (none or startOver). By default none"
167
                }
168
              }
169
            },
170
            "steps": {
171
              "type": "array",
172
              "description": "A list of steps to execute.",
173
              "items": {
174
                "type": "object",
175
                "description": "A description of the step to execute.",
176
                "required": ["action"],
177
                "properties": {
178
                  "id": {
179
                    "type": "string",
180
                    "description": "The ID of the step, which can be used to refer to its outputs."
181
                  },
182
                  "name": {
183
                    "type": "string",
184
                    "description": "The name of the step, which will be displayed in the UI during the scaffolding process."
185
                  },
186
                  "action": {
187
                    "type": "string",
188
                    "description": "The name of the action to execute."
189
                  },
190
                  "input": {
191
                    "type": "object",
192
                    "description": "A templated object describing the inputs to the action."
193
                  },
194
                  "if": {
195
                    "type": ["string", "boolean"],
196
                    "description": "A templated condition that skips the step when evaluated to false. If the condition is true or not defined, the step is executed. The condition is true, if the input is not `false`, `undefined`, `null`, `\"\"`, `0`, or `[]`."
197
                  },
198
                  "backstage:permissions": {
199
                    "type": "object",
200
                    "description": "Object used for authorizing the step",
201
                    "properties": {
202
                      "tags": {
203
                        "type": "array",
204
                        "items": {
205
                          "type": "string"
206
                        }
207
                      }
208
                    }
209
                  }
210
                }
211
              }
212
            },
213
            "output": {
214
              "type": "object",
215
              "description": "A templated object describing the outputs of the scaffolding task.",
216
              "properties": {
217
                "links": {
218
                  "type": "array",
219
                  "description": "A list of external hyperlinks, typically pointing to resources created or updated by the template",
220
                  "items": {
221
                    "type": "object",
222
                    "required": [],
223
                    "properties": {
224
                      "url": {
225
                        "type": "string",
226
                        "description": "A url in a standard uri format.",
227
                        "examples": ["https://github.com/my-org/my-new-repo"],
228
                        "minLength": 1
229
                      },
230
                      "entityRef": {
231
                        "type": "string",
232
                        "description": "An entity reference to an entity in the catalog.",
233
                        "examples": ["Component:default/my-app"],
234
                        "minLength": 1
235
                      },
236
                      "title": {
237
                        "type": "string",
238
                        "description": "A user friendly display name for the link.",
239
                        "examples": ["View new repo"],
240
                        "minLength": 1
241
                      },
242
                      "icon": {
243
                        "type": "string",
244
                        "description": "A key representing a visual icon to be displayed in the UI.",
245
                        "examples": ["dashboard"],
246
                        "minLength": 1
247
                      }
248
                    }
249
                  }
250
                },
251
                "text": {
252
                  "type": "array",
253
                  "description": "A list of Markdown text blobs, like output data from the template.",
254
                  "items": {
255
                    "type": "object",
256
                    "required": [],
257
                    "properties": {
258
                      "title": {
259
                        "type": "string",
260
                        "description": "A user friendly display name for the text.",
261
                        "examples": ["Output Content"],
262
                        "minLength": 1
263
                      },
264
                      "icon": {
265
                        "type": "string",
266
                        "description": "A key representing a visual icon to be displayed in the UI.",
267
                        "examples": ["dashboard"],
268
                        "minLength": 1
269
                      },
270
                      "content": {
271
                        "type": "string",
272
                        "description": "The text blob to display in the UI, rendered as Markdown.",
273
                        "examples": ["**hey** _I'm_ Markdown"]
274
                      }
275
                    }
276
                  }
277
                }
278
              },
279
              "additionalProperties": {
280
                "type": "string"
281
              }
282
            }
283
          }
284
        }
285
      }
286
    }
287
  ]
288
}
289