New Step description (#21)

* Update step.yml * Update step.yml * Update step.yml * Update step.yml * Update step.yml * Update step.yml * Revert "Update step.yml" This reverts commit 8639a90. * Revert "Update step.yml" This reverts commit 53a7193. * Revert "Update step.yml" This reverts commit 1def020. * Update step.yml * fixing missing attributes * Update step.yml * formatting fixes * adding summary Co-authored-by: Akos Birmacher <[email protected]> Co-authored-by: Akos Birmacher <[email protected]> Co-authored-by: Olivér Falvai <[email protected]>
bitrise-steplib · Sep 13, 2021 · 0e94e77 · 0e94e77
1 parent 91166a6
commit 0e94e77
Showing 1 changed file with 59 additions and 12 deletions.
diff --git a/step.yml b/step.yml
@@ -1,6 +1,48 @@
 title: "Bitrise Start Build"
-summary: "Starts the given workflows in the same app"
-description: "Starts the given workflows in the same app"
+summary: Starts a new build with the specified Workflow(s).
+description: |-
+  The Step starts a new build of the same app. In combination with the **Bitrise Wait for Build** Step you can use this Step to start multiple builds that run in parallel at the same time. You can put this Step in a Workflow that is triggered by a code push or pull request and use this Step to trigger multiple other builds at the same time. 
+  
+  To do that, you need multiple concurrencies - at least two! You also need a Personal Access Token to use the Step: [check out our guide](https://devcenter.bitrise.io/getting-started/account-security/#generating-personal-access-tokens-manually) on how to generate the token.
+  
+  ### Configuring the Step 
+  
+  Before you run a build with this Step, make sure you have your Personal Access Token stored in a [Secret Environment Variable](https://devcenter.bitrise.io/builds/env-vars-secret-env-vars/#adding-a-secret-env-var).
+  
+  Note that all builds you trigger using this Step will have the same build number! 
+  
+     1. Set up at least two Workflows in the Workflow Editor: one will contain the Step, the other will be triggered by the Step. 
+       You can set up as many Workflows as you wish: your number of concurrencies limit the number of Workflows you can run simultaneously.
+    2. Add the **Bitrise Start Build** Step to the part of the Workflow where you want to trigger another build. 
+    3. Add the Secret Env Var storing your Personal Access Token to the **Bitrise Access Token** input of the **Bitrise Start Build** Step: click the **Select secret variable** button, and choose the key you created.
+    4. Find the **Workflows** input of the **Bitrise Start Build** Step, and add the Workflow(s) you want to run. 
+    5. In the **Environments to share** input, add Environment Variables (Env Vars) that you want to share between the builds triggered by the Step. 
+    6. Add the **Bitrise Wait for Build** Step to the end of Workflow that contains the **Bitrise Start Build** Step. 
+    7. Add the Secret Env Var storing your Personal Access Token to the **Bitrise Access Token** input of the **Bitrise Wait for Build** Step: click the **Select secret variable** button, and choose the key you created.
+    8. In the **Build slugs** input, define the builds for the Step. 
+       The build slugs you need are stored by the **Bitrise Start Build** Step in the `$ROUTER_STARTED_BUILD_SLUGS` Env Var. As long as the builds defined by the slugs are running, the Step will hold the build it is running in. The build will fail if any of the builds included in the Step fail.
+    9. Optionally, you can save the build artifacts from the builds and configure the Step to abort all builds if any of the builds fail:
+       - In **The path of the build artifacts** input, set where you'd like to save the artifacts. 
+         The value of the input must be an actual, existing path, ending with `/`. The `BITRISE_DEPLOY_DIR` Environment Variable is NOT a valid value.
+       - Set the **Abort all builds if one fails** input to either `yes` or `no`. 
+       Please note that the build artifacts of child Workflows - Workflows triggered by this Step - will be only available if the child Workflow contains a **Deploy to Bitrise.io** Step.
+  
+  ### Troubleshooting 
+
+  - Make sure you have both the **Bitrise Start Build** and the **Bitrise Wait for Build** Steps in the right place in your initial Workflow. 
+  - Always check all your builds: if your concurrencies are taken up by other builds, this Step cannot start new ones. 
+  - Your Personal Access Token can expire! Make sure it's still valid - without it, you can't start new builds with this Step.  
+
+  ### Useful links 
+
+  - [Starting parallel builds with a single Workflow](https://devcenter.bitrise.io/builds/triggering-builds/trigger-multiple-Workflows/)
+
+  ### Related Steps 
+
+  - [Bitrise Wait for Build](https://www.bitrise.io/integrations/steps/build-router-start)
+  - [Bitrise Run](https://www.bitrise.io/integrations/steps/bitrise-run)
+  - [Build Status Change](https://www.bitrise.io/integrations/steps/build-status-change)
+
 website: https://github.com/bitrise-steplib/bitrise-step-build-router-start
 source_code_url: https://github.com/bitrise-steplib/bitrise-step-build-router-start
 support_url: https://github.com/bitrise-steplib/bitrise-step-build-router-start/issues
@@ -31,15 +73,15 @@ inputs:
   - workflows:
     opts:
       title: Workflows
-      summary: The workflow(s) to start. One workflow per line.
-      description: The workflow(s) to start. One workflow per line.
+      summary: The Workflow(s) to start. One Workflow per line.
+      description: The Workflow(s) to start. One Workflow per line.
       is_required: true
   - environment_key_list:
     opts:
       title: Environments to share
-      summary: The keys of the envs which will be shared with the triggered workflows.
+      summary: The keys of the envs which will be shared with the triggered Workflows.
       description: |-
-        The keys of the envs which will be shared with the triggered workflows
+        The keys of the envs which will be shared with the triggered Workflows
 
         
         **FORMAT** Seperate the keys with new line. E.g: 
@@ -51,23 +93,28 @@ inputs:
   - wait_for_builds: "false"
     opts:
       title: Wait for builds
-      summary: Should the step wait for the builds to be finished?
-      description: Should the step wait for the builds to be finished?
+      summary: Should the Step wait for the builds to be finished?
+      description: Should the Step wait for the builds to be finished?
       is_required: false
       value_options:
         - "false"
         - "true"
   - build_artifacts_save_path:
     opts:
-      title: Path to save the Artifacts in (leave empty to not save artifacts)
-      summary: This is where the artifacts will be saved to if wait_for_builds == true
+      title: The path of the build artifacts
+      summary: The path that the build artifacts will be saved to if the **Wait for builds** input is set to `true`.
       description: |
-          This is where the artifacts will be saved to so you can access them in the workflow
+          The path where build artifacts will be saved to if the **Wait for builds** input is set to `true`. 
+      
+          Please note that the path must be an actual, existing path, ending with `/`. The `BITRISE_DEPLOY_DIR` Environment Variable is NOT a valid value. 
+      
+          Note that when this Step triggers a Workflow, the artifacts of the triggered Workflow are only available to the Workflow that contains this Step, and not other Workflows. 
+          The triggered Workflow MUST have a **Deploy to Bitrise.io** Step to deploy build artifacts!
       is_required: false
       is_sensitive: false
   - abort_on_fail: "no"
     opts:
-      title: Abort all if any fail
+      title: Abort all builds if any of them
       description: |-
         Abort all started builds if any build fails
       is_required: true