Skip to content

Commit

Permalink
Merge pull request #137 from buildkite/docs-public-pr-3011
Browse files Browse the repository at this point in the history 
Improve/Standardize `alias`
  • Loading branch information
@gilesgas
gilesgas authored Nov 26, 2024
2 parents 6b82b7e + 8cb9996 commit 5e6f1b2
Show file tree
Hide file tree
Showing 6 changed files with 199 additions and 169 deletions.
80 changes: 41 additions & 39 deletions pages/pipelines/configure/step_types/block_step.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -57,60 +57,62 @@ Optional attributes:
<tr>
<td><code>prompt</code></td>
<td>
<p>The instructional message displayed in the dialog box when the unblock step is activated.</p>
<p><em>Example:</em></p>
The instructional message displayed in the dialog box when the unblock step is activated.
<em>Example:</em>
<ul><li> <code>"Release to production?"</code></li><li><code>"Fill out the details for this release"</code></li></ul>
</td>
</tr>
<tr>
<td><code>fields</code></td>
<td>
<p>A list of input fields required to be filled out before unblocking the step.</p>
<p>Available input field types: <code>text</code>, <code>select</code></p>
A list of input fields required to be filled out before unblocking the step.
Available input field types: <code>text</code>, <code>select</code>
</td>
</tr>
<tr>
<td><code>blocked_state</code></td>
<td>
<p>The state that the build is set to when the build is blocked by this block step. The default is passed. When the <code>blocked_state</code> of a block step is set to <code>failed</code>, the step that triggered it will be stuck in the <code>running</code> state until it is manually unblocked.</p>
<p><em>Default:</em> <code>passed</code></p>
<p><em>Values:</em> <code>passed</code>, <code>failed</code>, <code>running</code></p>
<p>If you're using GitHub, you can also <a href="/docs/pipelines/source-control/github#customizing-commit-statuses">configure which GitHub status</a> to use for blocked builds on a per-pipline basis.</p>
The state that the build is set to when the build is blocked by this block step. The default is passed. When the <code>blocked_state</code> of a block step is set to <code>failed</code>, the step that triggered it will be stuck in the <code>running</code> state until it is manually unblocked.
<em>Default:</em> <code>passed</code>
<em>Values:</em> <code>passed</code>, <code>failed</code>, <code>running</code>
If you're using GitHub, you can also <a href="/docs/pipelines/source-control/github#customizing-commit-statuses">configure which GitHub status</a> to use for blocked builds on a per-pipeline basis.
</td>
</tr>
<tr>
<td><code>branches</code></td>
<td>
<p>The <a href="/docs/pipelines/configure/workflows/branch-configuration#branch-pattern-examples">branch pattern</a> defining which branches will include this block step in their builds.</p>
<p><em>Example:</em> <code>"main stable/*"</code></p>
The <a href="/docs/pipelines/configure/workflows/branch-configuration#branch-pattern-examples">branch pattern</a> defining which branches will include this block step in their builds.
<em>Example:</em> <code>"main stable/*"</code>
</td>
</tr>
<tr>
<td><code>if</code></td>
<td>
<p>A boolean expression that omits the step when false. See <a href="/docs/pipelines/configure/conditionals">Using conditionals</a> for supported expressions.</p>
<p><em>Example:</em> <code>build.message != "skip me"</code></p>
A boolean expression that omits the step when false. See <a href="/docs/pipelines/configure/conditionals">Using conditionals</a> for supported expressions.
<em>Example:</em> <code>build.message != "skip me"</code>
</td>
</tr>
<tr>
<td><code>depends_on</code></td>
<td>
<p>A list of step keys that this step depends on. This step will only proceed after the named steps have completed. See <a href="/docs/pipelines/configure/dependencies">managing step dependencies</a> for more information.</p>
<p><em>Example:</em> <code>"test-suite"</code></p>
A list of step keys that this step depends on. This step will only proceed after the named steps have completed. See <a href="/docs/pipelines/configure/dependencies">managing step dependencies</a> for more information.
<em>Example:</em> <code>"test-suite"</code>
</td>
</tr>
<tr>
<td><code>key</code></td>
<td>
<p>A unique string to identify the block step.</p>
<p><em>Example:</em> <code>"test-suite"</code></p>
A unique string to identify the block step.<br/>
Keys can not have the same pattern as a UUID (<code>xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx</code>).
<em>Example:</em> <code>"test-suite"</code>
<em>Alias:</em> <code>identifier</code>
</td>
</tr>
<tr>
<td><code>allow_dependency_failure</code></td>
<td>
<p>Whether to continue to proceed past this step if any of the steps named in the <code>depends_on</code> attribute fail.</p>
<p><em>Default:</em> <code>false</code></p>
Whether to continue to proceed past this step if any of the steps named in the <code>depends_on</code> attribute fail.
<em>Default:</em> <code>false</code>
</td>
</tr>
</table>
Expand All @@ -133,9 +135,9 @@ Required attributes:
<tr>
<td><code>key</code></td>
<td>
<p>The meta-data key that stores the field's input (using the <a href="/docs/agent/v3/cli-meta-data">buildkite-agent meta-data command</a>)<br>
The key may only contain alphanumeric characters, slashes, dashes, or underscores.</p>
<p><em>Example:</em> <code>"release-name"</code></p>
The meta-data key that stores the field's input (using the <a href="/docs/agent/v3/cli-meta-data">buildkite-agent meta-data command</a>)<br/>
The key may only contain alphanumeric characters, slashes, dashes, or underscores.
<em>Example:</em> <code>"release-name"</code>
</td>
</tr>
</table>
Expand All @@ -156,22 +158,22 @@ Optional attributes:
<tr>
<td><code>hint</code></td>
<td>
<p>The explanatory text that is shown after the label.</p>
<p><em>Example:</em> <code>"What's the code name for this release? \:name_badge\:"</code></p>
The explanatory text that is shown after the label.
<em>Example:</em> <code>"What's the code name for this release? \:name_badge\:"</code>
</td>
</tr>
<tr>
<td><code>required</code></td>
<td>
<p>A boolean value that defines whether the field is required for form submission.</p>
<p><em>Default value:</em> <code>true</code></p>
A boolean value that defines whether the field is required for form submission.
<em>Default value:</em> <code>true</code>
</td>
</tr>
<tr>
<td><code>default</code></td>
<td>
<p>The value that is pre-filled in the text field.</p>
<p><em>Example:</em> <code>"Flying Dolphin"</code></p>
The value that is pre-filled in the text field.
<em>Example:</em> <code>"Flying Dolphin"</code>
</td>
</tr>
</table>
Expand All @@ -197,16 +199,16 @@ Required attributes:
<tr>
<td><code>key</code></td>
<td>
The meta-data key that stores the field's input (using the <a href="/docs/agent/v3/cli-meta-data">buildkite-agent meta-data command</a>)<br>
The meta-data key that stores the field's input (using the <a href="/docs/agent/v3/cli-meta-data">buildkite-agent meta-data command</a>)<br/>
The key may only contain alphanumeric characters, slashes, dashes, or underscores.
<em>Example:</em> <code>"release-stream"</code>
</td>
</tr>
<tr>
<td><code>options</code></td>
<td>
The list of select field options.<br>
For 6 or less options they'll be displayed as radio buttons, otherwise they'll be displayed in a dropdown box.<br>
The list of select field options.<br/>
For 6 or less options they'll be displayed as radio buttons, otherwise they'll be displayed in a dropdown box.<br/>
If selecting multiple options is permitted the options will be displayed as checkboxes.
</td>
</tr>
Expand All @@ -218,14 +220,14 @@ Each select option has the following _required_ attributes:
<tr>
<td><code>label</code></td>
<td>
The text displayed for the option.<br>
The text displayed for the option.<br/>
<em>Example:</em> <code>"Stable"</code>
</td>
</tr>
<tr>
<td><code>value</code></td>
<td>
The value to be stored as meta-data (to be later retrieved using the <a href="/docs/agent/v3/cli-meta-data">buildkite-agent meta-data command</a>)<br>
The value to be stored as meta-data (to be later retrieved using the <a href="/docs/agent/v3/cli-meta-data">buildkite-agent meta-data command</a>)<br/>
<em>Example:</em> <code>"stable"</code>
</td>
</tr>
Expand All @@ -252,31 +254,31 @@ Optional attributes:
<tr>
<td><code>hint</code></td>
<td>
The text displayed directly under the select field's label.<br>
The text displayed directly under the select field's label.<br/>
<em>Example:</em> <code>"Which release stream does this belong in? \:fork\:"</code>
</td>
</tr>
<tr>
<td><code>required</code></td>
<td>
A boolean value that defines whether the field is required for form submission.<br>
When this value is set to <code>false</code> and users can only select one option, the options display in a dropdown menu, regardless of how many options there are.<br>
A boolean value that defines whether the field is required for form submission.<br/>
When this value is set to <code>false</code> and users can only select one option, the options display in a dropdown menu, regardless of how many options there are.<br/>
<em>Default:</em> <code>true</code>
</td>
</tr>
<tr>
<td><code>multiple</code></td>
<td>
A boolean value that defines whether multiple options may be selected.<br>
When multiple options are selected, they are delimited in the meta-data field by a line break (<code>\n</code>)<br>
A boolean value that defines whether multiple options may be selected.<br/>
When multiple options are selected, they are delimited in the meta-data field by a line break (<code>\n</code>)<br/>
<em>Default:</em> <code>false</code>
</td>
</tr>
<tr>
<td><code>default</code></td>
<td>
The value of the option or options that will be pre-selected.<br>
When <code>multiple</code> is enabled, this can be an array of values to select by default.<br>
The value of the option or options that will be pre-selected.<br/>
When <code>multiple</code> is enabled, this can be an array of values to select by default.<br/>
<em>Example:</em> <code>"beta"</code>
</td>
</tr>
Expand Down
Loading

0 comments on commit 5e6f1b2

Please sign in to comment.