Skip to main content

Configuring Pipelines

概要

Configure a Bitrise Pipeline by adding Workflows and optionally, defining dependencies between the Workflows.

Pipelines with stages

If you have an existing Pipeline configuration from before December 2024, you probably have stages in your Pipeline. We strongly recommend to stop using stages and instead focus on configuring dependencies between Workflows. These dependencies determine the order of execution in a Pipeline. This eliminates unnecessary waiting time in stages and allows you to create more flexible CI configurations.

You can keep using Pipelines with stages but they will receive no new features in the future. You can have both types of Pipelines in the same configuration YAML file but you can't mix and match the two types: you can't have both stages and Workflow dependencies in the same Pipeline.

You can find the documentation for Pipelines with stages here: パイプラインの構築[ベータ版].

You can define your Pipelines under a pipelines element in a configuration YAML file. You can use the following elements to set up a Pipeline:

  • A Pipeline name: the human readable identifier of the Pipeline.

  • The workflows element: this contains a list of the Workflows that are part of the Pipeline.

  • The depends_on property: This is a property of the workflows element and accepts an array of Workflow names. It defines the dependencies between Workflows.

For example, here's a simple Pipeline configuration:

pipeline-example.png

In this Pipeline, we have four Workflows:

  1. Workflow A runs first.

  2. Once Workflow A is finished, Workflows B and C start at the same time.

  3. Workflow D starts only when both Workflows B and C are successfully finished.

Creating a Pipeline

Workflow Editor

Configuration YAML

Open the Workflow Editor and select Pipelines on the left. Click Create Pipeline.

To add your first Workflow, click Workflows.

add-workflow-pipeline.png

You can keep adding Workflows this way. This method creates no dependencies between Workflows: they will all run at the same time.

basic-pipeline.png

To create Workflow dependencies, hover over the right end of a Workflow and click the plus sign:

add-dependent-workflow.png

You can add multiple dependent Workflows to the same Workflow this way:

multiple-dependent-flows.png

The same Workflow can depend on two or more different Workflows: you can create a path by dragging from the plus sign to another Workflow already in the Pipeline:

drag-and-drop-dep.png

A bare minimum Pipeline configuration consists of a single Workflow:

pipelines:
  example:
    workflows:
      A: {}

You can have multiple Workflows that all run in parallel:

pipelines:
  example:
    workflows:
      A: {}
      B: {}
      C: {}

To create Workflow dependencies like the example above, you need to use the depends_on property:

pipelines:
  example:
    workflows:
      A: {}
      B:
        depends_on:
        - A
      C:
        depends_on:
        - A
      D:
        depends_on:
        - B
        - C

If a Workflow depends on multiple Workflows, both YAML array syntaxes can be used:

# Option 1
D:
  depends_on:
  - B
  - C
# Option 2
D:
  depends_on: [A, B]

Configuration restrictions

  • A Pipeline can have a maximum of 50 Workflows. Each must be an existing Workflow under the root level workflows element.

  • Utility Workflows can't be added to a Pipeline. If you want to use utility Workflows, include them as part of a regular Workflow.

  • Each Workflow can be added to the same Pipeline only once. You can't include the same Workflow in multiple different parts of a Pipeline.

  • Any Workflow defined in the dependency list must be part of the same Pipeline.

  • The dependency graph resulting from your configuration can't contain a circle or loop. Such an error will builds from starting.

Conditional Workflow execution in a Pipeline

Use run_if expressions to control Workflow execution: you can set conditions under which a Workflow should or should not run.

Workflow Editor

Configuration YAML

  1. Open your Pipeline.

  2. Hover over the Workflow you need and click the gear icon to open the Edit Workflow dialog.

    workflow-properties-edit.png

  3. Select Pipeline Conditions.

  4. In the Additional running conditions input, add a valid Go template.

    The input accepts three helper functions:

    • getenv: Accesses an Environment Variable's value.

    • enveq: Compares an Environment Variable to a given value.

    • envcontain: Checks whether an Environment Variable contains a given string.

    run-if-template.png

  5. Close the Edit Workflow dialog, and click Save changes.

In Pipelines, the run_if property needs an expression field that contains a Go template:

pipelines:
  example:
    workflows:
      A: {}
      B:
        run_if:
          expression: {{ enveq "EXAMPLE_KEY" "example value" }}
        depends_on: [A]

The expression field accepts three helper functions:

  • getenv: Accesses an Environment Variable's value.

  • enveq: Compares an Environment Variable to a given value.

  • envcontain: Checks whether an Environment Variable contains a given string.

The Bitrise CLI evaluates the expression during runtime: a Workflow only runs if its run_if expression evaluates to true. A Workflow that is skipped because of a run_if expression is counted as a successful Workflow so its dependent Workflows will run.

In this example, B will only run if the EXAMPLE_KEY Environment Variable has the value example value.

Always executing a Workflow in a Pipeline

You can mark a Workflow to make sure it runs even if a Workflow it depends on failed.

Transitive dependency

Even if a Workflow is configured to always run, its dependent Workflows might not run. If one or more of its parent Workflows failed, the Workflow in question will still run but its dependent Workflows might not.

For example, let's say we have Workflow C that depends on Workflow B. Workflow B depends on Workflow A. Of the three Workflows, only B is set to always run:

  • If A fails, B will run but regardless of its result, C won't run because by depending on B, it also depends on A.

  • C only runs if both A and B are successful.

Workflow Editor

Configuration YAML

  1. Open your Pipeline.

  2. Hover over the Workflow you need and click the gear icon to open the Edit Workflow dialog.

    workflow-properties-edit.png

  3. Select Pipeline Conditions.

  4. Set the Always run input to Workflow.

    This setting means the Workflow will run even if one or more of its parent Workflows fail. However, its dependent Workflows might not run!

Use the should_always_run property. It requires a string to specify the scope of the configuration. It has two available values:

  • none: If a parent Workflow fails, the Workflow will not run. This is the default value.

  • workflow: If a parent Workflow fails, the Workflow will run anyway.

pipelines:
  example:
    workflows:
      A: {}
      B:
        depends_on: [ A ]
        should_always_run: workflow
      C:
        depends_on: [ B ]
      D:
        depends_on: [ C ]
        should_always_run: workflow

In this example:

  • If A fails, B still runs.

  • If either A or B fails, C won't run.

  • If C won't run or runs but fails, D will still run.

Aborting the Pipeline on Workflow failure

You can configure the Pipeline to immediately terminate when any given Workflow fails. By default, the Pipeline won't terminate

Workflow Editor

Configuration YAML

  1. Open your Pipeline.

  2. Hover over the Workflow you need and click the gear icon to open the Edit Workflow dialog.

    workflow-properties-edit.png

  3. Select Pipeline Conditions.

  4. Toggle the Abort Pipeline on failure input on.

    If the Workflow in question fails, the Pipeline will immediately stop running.

Add the abort_on_fail field set to true to the selected Workflows:

pipelines:
  example:
    workflows:
      A: {}
      B:
        abort_on_fail: true

In this example, the Pipeline stops running if Workflow B fails: Workflow A will be aborted and no subsequent Workflows will run.

プル パイプライン中間ファイルの使用手順

前のステージでワークフローによって生成されたアーティファクトへのアクセスを必要とするワークフローがある場合は、 パイプライン中間ファイルのプル ステップ：

To configure file sharing:

Workflow Editor

Configuration YAML

  1. Add the Deploy to Bitrise.io Step to the Workflow that generates the file(s) you need.

  2. In the Pipeline Intermediate File Sharing input group, find the Files to share input and add the files as a newline-separated list of colon-separated items using the following structure: <file_or_directory_path>:<environment_variable_key>.

    You can use another Environment Variable as a filepath: for an iOS project, $BITRISE_IPA_PATH:BITRISE_IPA_PATH is a valid way to share a generated IPA with other Workflows.

  3. Add the Pull Pipeline intermediate files Step to any Workflow that needs the generated files.

  4. Use the Artifact source input to specify a set of Workflows from which you need files.

    pull-pipeline-art-source.png

    You can use wildcards in the input. In the example above, we’re pulling all artifacts from all Workflows which have a name starting with workflow.

  5. When the Step finishes, your files and directories specified via the Deploy to Bitrise.io - Apps, Logs, Artifacts Step should be available.

  1. Add the Deploy to Bitrise.io Step to the Workflow that generates the file(s) you need.

  2. Add the files to the pipeline_intermediate_files input as a newline-separated list of colon-separated items using the following structure: <file_or_directory_path>:<environment_variable_key>.

    You can use another Environment Variable as a filepath: for an iOS project, $BITRISE_IPA_PATH:BITRISE_IPA_PATH is a valid way to share a generated IPA with other Workflows.

    steps:
  - deploy-to-bitrise-io: {
      inputs:        
      - pipeline_intermediate_files: "$BITRISE_IPA_PATH:BITRISE_IPA_PATH"

  3. 追加 パイプライン中間ファイルのプル ワークフローへのステップ (通常、ワークフローの開始時、または共有ファイルに依存するステップの前):

    steps:
  - pull-intermediate-files: {}

  4. 使用 artifact_sources ステージとワークフローのセットを指定するための入力。入力の構文は次のとおりです。 {stage-name}.{workflow-name}:

    steps:
  - pull-intermediate-files@1:
      inputs:
        - artifact_sources: workflow.*

    上記の例では、ステージ内のすべてのワークフローからすべてのアーティファクトを取得しています。 stage-1.

  5. ステップが終了すると、ファイルとディレクトリが Bitrise.io へのデプロイ - アプリ、ログ、アーティファクト ステップが復元されます。

詳細については、 ステップ リポジトリ.

Sharing Env Vars between Workflows

から任意の環境変数を再利用できます。 ワークフロー その後で再利用します ステージ を使用して パイプライン変数を共有するステップ.このステップを使用して環境変数を共有しても、 アプリ.

run_if 条件を使用したオプションのワークフロー

簡単に組み合わせることができます パイプライン変数を共有する ステップ run_if オプションのワークフローでパイプラインを作成するための式。詳細については、こちらをご覧ください パイプラインを使用したオプションのワークフローの run_if 条件の設定.パイプラインを使用したオプションのワークフローの run_if 条件の設定

そうするために：

  1. 追加 パイプライン変数を共有する ワークフローに進みます。

  2. 必要に応じて、追加の実行条件を 追加の実行条件 入力。ステップは、ここで指定した条件が真の場合にのみ実行されます。

  3. 後続のステージで使用する環境変数を パイプライン ステージ間で共有する変数 入力。

    環境変数キーの使用

    を使用して環境変数を定義できます。{key}={value}構文。例えば、 MY_ENV_KEY=value、 また INSTALL_PAGE_URL=$BITRISE_PUBLIC_PAGE_URL.

    デフォルトの環境変数キーを使用する場合は、簡略構文を使用できます。例えば、 EXISTING_ENV_KEY.

    このステップを使用して環境変数を共有しても、 アプリ.

このセクションの内容:
参照:
ワークフローステージステップアプリアプリ