新しいステップの開発

重複する手順

新しいステップの開発を決定する前に、同じ機能を実行する既存のステップがないことを確認してください。

あなたは私たちのステップを検索することができます 統合 ページまたは ステップライブラリ GitHubで。

ステップはビルドタスクです。たとえば、 Gitクローン ステップは、ビルドの開始時にGitリポジトリのクローンを作成します。 GooglePlayデプロイ ステップは、完成したアプリをPlayストアにデプロイできます。

ステップには、ビルドタスクを実行するコードが含まれています。タスクを定義する入力とパラメーターを構成し、ステップが生成する出力を表示して再利用できます。出力を再利用するということは、別のステップがそれを入力の1つの値として使用できることを意味します。

私たちのステップはで書かれています 行け またはBash。ステップは独自のGitリポジトリに含まれています:コードと step.yml ステップの構成を定義するファイル。ステップを他のユーザーが利用できるようにしたい場合は、 step.yml ファイルはに含まれている必要があります bitrise-steplib 他のユーザーがワークフローエディターで当社のWebサイトのステップを見つけることができるようにリポジトリ。

手順の共有

カスタムステップの共有はオプションです。単一のユーザーに固有のユースケースを持つステップは、他のユーザーにはあまり役立ちません。自分のマシンまたは任意のGitリポジトリからステップを実行できるため、カスタムステップはBitriseステップライブラリの一部である必要はありません。

他のユーザーとステップを共有する方法の詳細については、 手順の共有 ガイド。

ステップの動作の詳細については、次のガイドを参照してください。

新しいステップの開発を開始する前に

新しいステップを作成する前に、Bitrise CLIをインストールしてセットアップし、 ステッププラグイン 最新バージョンに更新されます。

  1. BitriseCLIをインストールします。

  2. ビットライズセットアップを実行します。

  3. 次のコマンドを使用して、Stepプラグインを最新バージョンに更新します。

    bitrise plugin update step

ステップの作成

Bitrise CLIのStepプラグインを使用して、新しいStepを作成します。これで、ステップの基本構造を作成します。特定のプロパティと入力が自動的に生成され、割り当てられます。後で何でも変更できるので、まだ心配しないでください。

ステッププラグイン

走る bitrise :step コマンドラインインターフェイスでコマンドを確認します。

ステップの基本構造の作成は簡単です。このプロセスに関連する概念については、後で詳しく説明します。今のところ、ステップを作成するプロセスを実行するだけです。このプロセスの最後に、 step.yml ファイル、 README.md ファイルといずれか main.go または step.sh リポジトリ内のファイル。

始める前に

ステップの作成プロセス中に、いくつかのオプションを設定するように求められます。ステップをBitriseに送信して確認する前に、これらのいずれかを変更できることに注意してください。データは生成されたものに含まれます。 step.yml 後で自由に編集できるファイル。最初のステップ作成プロセス中に、必要に応じてプレースホルダーを使用できます。

  1. MacOSのターミナルアプリなどのコマンドラインインターフェイスを開きます。

  2. まだ作成していない場合は、ステップ用の新しいディレクトリを作成し、そのディレクトリを入力します。

  3. BitriseStepプラグインを使用してステップを作成します。

  4. プロンプトが表示されたら、ステップの作成者の名前を設定します。

    Enterキーを押して、デフォルト値のままにします。

  5. プロンプトが表示されたら、ステップの名前を設定します。

    プラグインは、この名前に基づいてステップIDを自動的に生成します。

  6. 要約を提供します:ステップが何をするかについてのほんの数文。

  7. ステップの説明を提供します。

    これには、ステップの構成情報とトラブルシューティング情報が含まれている必要があります。

  8. ステップのプライマリカテゴリを選択します。

    これを行うには、希望するオプションの番号を入力して、Enterキーを押します。これは後で変更できます。

  9. 使用するツールキットを選択します。GoまたはBashのいずれかを選択できます。

  10. ステップのデータをホストするソースコードを設定します。

    これを行うには、最初にGitHubでホストするか、他のサイトでホストするかを決定し、適切なオプションを入力します。

    • GitHubを選択した場合は、リポジトリを所有するアカウントのユーザー名を入力するように求められます。

    • GitHubに保存しないことを選択した場合は、リポジトリの有効なURLを指定する必要があります。

完了です!すべてがうまくいった場合、プラグインは現在のディレクトリのgitリポジトリを初期化し、 step.yml、 NS README.md ファイル、およびいずれか main.go または main.sh ファイル。

次に、 step.yml ファイルが機能し、その設定方法。

step.ymlファイル

NS step.yml fileは、ステップインターフェイス定義であり、依存関係、ステップ入力、ステップ出力、およびその他のステッププロパティが含まれています。また、ステップのソースコードの場所も示します。すべてのステップに1つ必要です。

ステッププラグインを使用して新しいステップを作成する場合、必要なすべてのプロパティに値が割り当てられますが、いつでも変更できます。したがって、最初のプロセスで設定したタイトルが以下のガイドラインに準拠していなくても心配する必要はありません。

の最も重要な構成オプションを見ていきます。 step.yml ステップの命名と説明、およびステップ入力とステップ出力の設定を含むファイル。

ステップの命名と説明

すべてのステップには、少なくともタイトルと要約が定義されている必要があります。 step.yml ファイル。これらは両方に表示されます 統合 ページと ワークフローエディター。 NS description プロパティはオプションですが、他のユーザーがステップの動作をよりよく理解できるように、プロパティを提供することを強くお勧めします。

説明と要約

両方 descriptionsummary その値でMarkdownフォーマットを受け入れます。

タイトル

タイトルプロパティ

NS title プロパティが必要です!

NS title プロパティは、ステップの名前を設定します。 bitrise.io。短くて説明的なものにする必要があります。サービスの名前と、サービスが実行する機能などを含めます。 Gitクローン。ステップタイトルのガイドラインは次のとおりです。

  • 「ステップ」という言葉は使用しないでください。

  • 可能な場合は、名詞の代わりに命令動詞を使用してください。たとえば、代わりに スクリプトランナー、 そのはず スクリプトを実行する

  • プラットフォームの名前は含めないでください。

  • サービスまたはツールの正しい名前を使用していることを確認してください。たとえば、GithubではなくGitHubです。

  • 実装の詳細は含めないでください。

サマリー

サマリープロパティ

サマリープロパティが必要です!

ステップに関する最も重要な情報の1行。 100文字を超えることはできません。

要約は、デフォルトでワークフローエディターに表示されます。ユーザーが要約を展開すると、ステップの説明が表示されます。もちろん、要約がある場合はその説明が表示されます。

説明

ステップの詳細な説明。以下を含める必要があります。

  • ステップが行うこと。

  • ステップで使用されるサービスとツール。

  • 最も重要な入力を含む構成情報。

  • トラブルシューティング情報:潜在的な問題とその解決策。

デフォルトでは、ステップの説明はワークフローエディターで折りたたまれ、概要が表示されます。

ステップカテゴリ

あなたのステップについて私たちが知りたいもう一つのことがあります:それはどのタイプのステップですか?統合ページまたはワークフローエディターで確認できるように、ステップは、使用可能なプラットフォームと機能の2つの要素に基づいてさまざまなカテゴリに分類されます。

プラットフォーム

利用可能なプラットフォームタイプは、 project_type_tags 属性。ステップがすべてのプラットフォームまたはプロジェクトタイプで利用できる場合は、指定しないでください project_type_tags。それ以外の場合は、ステップを使用できるすべてのプラットフォームタイプを選択してください。

使用可能な値は次のとおりです。

  • ios

  • macos

  • android

  • xamarin

  • react-native

  • cordova

  • ionic

  • flutter

カテゴリー

機能カテゴリは、 type_tags step.ymlの属性。 1つのステップには、単一のタイプタグのみを割り当てる必要があります。使用する utility 他のタイプのどれもあなたのステップに合わないとあなたが信じる場合にのみ。

使用可能な値は次のとおりです。

  • build

  • code-sign

  • test

  • deploy

  • notification

  • access-control

  • artifact-info

  • installer

  • dependency

  • utility

ステップ入力

ステップ入力はビットライズです 環境変数:これらは、ステップのユーザーがステップの動作を制御するために設定できるキーと値のペアで構成されます。たとえば、 Gitクローン ステップには、キーブランチを含む入力があります。

title: Git Clone Repository
summary: Clone a repository to the specified path on the VM
inputs:
- branch: master 

この入力の値(上記の例ではmaster)は、リポジトリのどのブランチが複製されるかを決定するために使用されます。

ステップ入力はワークフローエディターに表示されます。ステップ入力は、に表示される順序で表示されます。 step.yml。そのため、必須で頻繁に使用される入力を一番上に配置する必要があります。

ステップ入力キーと値

小文字を使用する スネークケース スタイル入力キー。例えば、 project_path

使用する opts 入力キーとして

入力キーはできません opts、入力のオプションに使用されるため。

入力はステップ実行プロセスでのみ公開されるため、入力キーにドメイン固有のプレフィックスを追加する必要はありません。これの意味は project_path 入力は後続のステップと重複しません。 project_path 入力。

ステップ入力値は文字列です。BitriseCLIは、ステップ入力を環境変数としてステップに公開します。

可能であれば(そしてそれが理にかなっている場合は)ステップ入力のデフォルト値を提供します。これにより、Bitriseユーザーはステップ構成が簡単になります。

次の場合を除いて、環境変数をデフォルト値として使用しないでください。

  • 彼らはによって公開されています BitriseCLIまたはbitrise.ioによる。

  • これらは、別のステップによって出力として生成されます(たとえば、 $BITRISE_IPA_PATH$BITRISE_AAB_PATH)。

これは、ワークフローエディターが値のない必要な入力を強調表示して、ステップを表現するために、指定された入力に有効な値を設定しないと機能しないためです。自動的に割り当てられた値を持たない環境変数を入力のデフォルト値として設定すると、ワークフローエディターは、問題の必要な入力に有効な値が設定されていると見なします(デフォルトの環境変数にまだ値がない場合でも) )。

また、この方法で環境変数に特定の名前を提案する理由はありません。ユーザーは、異なる名前の環境変数に同じ値が割り当てられている可能性があります。

ステップ入力がコードに渡される方法と、それらがどのように表示されるかについて説明しましょう。

ステップ入力の構成

ステップ入力は、 step.yml ファイル。

キーと値に加えて、ステップ入力には opts 財産。このプロパティには、入力がステップのコードに渡される方法と、ワークフローエディターでの表示方法を定義するさまざまなオプションが含まれています。入力の可能な値は、で設定できます。 opts 同様に。例を見てみましょう。

- install_defaults: "yes"
  opts:
    title: Installs default Codesign Files
    value_options:
    - "no"
    - "yes"

上記の入力にはキーinstall_defaultsがあり、そのデフォルト値はyesです。

value_optionsオプションは、可能な値を定義します。この場合、yesとnoです。そのoptsプロパティには、入力の表示方法に関する情報が含まれています。この場合、これは単なるタイトルオプションであり、常に必要です。入力のキーの代わりに、タイトルがワークフローエディタに表示されます。

NS value_options 入力

NS value_options 入力には文字列が含まれている必要があります。これは、例に示されているように、引用符がないと検証が失敗することを意味します。

ステップ入力の命名と説明

ステップ入力には、ステップ自体と同じように、名前、要約、および説明を含めることができます。これらを定義するには:

  1. 含める opts ステップ入力を持つプロパティ。

  2. optsの下に、タイトル、要約、および説明オプションを入力します。

これらがどのように見えるかを見てみましょう!

説明と要約

両方 descriptionsummary その値でMarkdownフォーマットを受け入れます。

  • title:短くて説明的な文または半文である必要があります:Xcodeプロジェクトのパス。内部で使用されるCLIフラグまたはAPIパラメーター名であってはなりません。これにより、基盤となるツールまたはサービスインターフェイスに関する既存の知識が不要になるため、ステップの構成が容易になります。また、下位互換性を維持しながら、ステップの実装を変更する方が簡単です。

  • summary:これは説明の短いバージョンであり、入力の概要を簡単に説明します。 Bitriseワークフローエディターでは、ステップをクリックすると、入力の概要がデフォルトで表示されます。

  • description:これは、ステップ入力のユーザー向けの説明です。これにより、入力のより深く、より詳細な説明が提供されます。デフォルトでは、ユーザーが問題の入力をクリックしない限り、ワークフローエディターには表示されません。

次に例を示します。

- install_defaults: "yes"
  opts:
    description: Installs default (Bitrise) Wildcard Provisioning Profile and
      Certificate files for testing.
    summary: Installs default (Bitrise) Wildcard code signing files.
    title: Installs default code signing files

それでは、ステップの他の構成オプションについて説明しましょう。

必要な入力

必要な入力には有効な値が必要です。そうでない場合、ステップは失敗します。

ステップ入力を必須としてマークするには、のis_requiredオプションを使用します opts 財産。 2つの値があります。 truefalse。に設定されている場合 true、入力は次のように表示されます 必要 ワークフローエディタで。

- keychain_password: $BITRISE_KEYCHAIN_PASSWORD
  opts:
    title: "Keychain's password"
    is_required: true

敏感な入力

ステップ入力をセンシティブとしてマークして、それらの値が公開されないようにすることができます。機密入力のみを受け入れます 秘密 値として。これにより、ビルドログに表示されなくなります。

ステップ入力を高感度としてマークするには、 is_sensitive のオプション opts 財産。 2つの値があります。 truefalse。に設定されている場合 true、入力は次のように表示されます センシティブ ワークフローエディタで。

NS is_expand オプション

入力を機密としてマークすると、 is_expand 入力のオプションもtrueである必要があります。これはデフォルト設定です。

inputs:
  - certificate_urls: $BITRISE_CERTIFICATE_URL
    opts:
      title: "Certificate URL"
      is_sensitive: true

EnvVarsを入力値として使用する

前述のように、任意の入力の値として環境変数を使用することができます。デフォルトでは、StepはEnv Varを展開し、その値をStepの実行に渡します。これはによって定義されます is_expand のオプション opts 財産。

- project_path: $BITRISE_PROJECT_PATH
  opts:
    is_expand: true

NS is_expand オプションには、trueまたはfalseの2つの値を指定できます。に設定されている場合 true -これはデフォルトの動作です-、の値 $BITRISE_PROJECT_PATH ステップ実行に渡されます。に設定されている場合 false、文字列 $BITRISE_PROJECT_PATH 合格します(プロジェクトの場所が見つからないため、この特定のステップは失敗します)。

ステップコードのEnv変数

ステップのコードで環境変数を直接使用しないでください。代わりに、すべての外部変数をステップの入力として公開し、その入力のデフォルト値を使用する環境変数に設定します。このようにして、ステップのテストが簡単になり、ステップのユーザーは、必要な変数のコードを精査することなく、これらの入力を簡単に宣言できます。

入力をグループ化する

カテゴリオプションは、入力をグループ化するために使用されます。同じカテゴリに属する入力は一緒に表示され、ワークフローエディタではデフォルトで折りたたまれています。

- default_certificate_passphrase: $BITRISE_DEFAULT_CERTIFICATE_PASSPHRASE
  opts:
    category: Default code signing files
    description: |
      Certificate passphrase of the default certificate.
    is_sensitive: true
    title: Default certificate passphrase

この場合、この入力は、同じカテゴリが設定されている他のすべての入力とともに表示されます。

ステップに6つを超える入力がある場合は、カテゴリを使用できます。グループまたはルートで推奨される入力の最大数は6です。

ステップカテゴリを設計するときは、次の点に注意してください。

  • 必要な入力はグループ化しないでください!

  • グループ化された入力は、分類されていない入力の後に表示する必要があります。

入力の値のリストを受け入れる

特定の入力の値のリストを受け入れることは絶対に可能です。これを行う場合は、入力のキーにリストサフィックスを追加することを強くお勧めします(たとえば、 input_path_list)、値が改行文字(\ n)で区切られたリストとして提供されることを期待します(たとえば、最初の値\ n2番目の値)。

値を区切るために本当に別の文字を使用する必要がない限り、このソリューションを使用してください。私たちの経験に基づくと、改行文字(\ n)は、入力値では非常にまれであるため(、、;、=または他のより一般的な区切り文字と比較して)、ユニバーサル区切り文字として非常にうまく機能します。

ベストプラクティスとして、空のアイテムを除外する必要があります。次のいずれかを使用します。

first value\n\nsecond value

また

first value\n       \nsecond value

ステップ出力

ステップは出力を生成でき、それを他のステップで入力として使用できます。つまり、ステップがアーティファクトを生成する場合、そのアーティファクトへのパスは、ビルド内の別のステップの入力になる可能性があります。たとえば、 iOS用のXcodeアーカイブとエクスポート ステップは、 $BITRISE_API_PATH 次に、の入力値として使用できる出力 iTunesConnectにデプロイする ステップ。

出力は、 step.yml ファイル、outputsプロパティの下。これらは入力と同じ構造を持っています。つまり、キーと値のペアで構成されています。出力のキーは、によって公開される環境変数と同様に、後続のステップで入力値として使用できます。 bitrise.io または、BitriseCLIを使用できます。

ステップ出力キーと値

出力キーには大文字を使用してください スネークケース スタイル出力キー。例:OUTPUT_PATH。

ステップ出力の命名と説明

ステップ入力の場合とは異なり、ステップ出力のタイトルと説明はワークフローエディターに表示されません。要約のみが表示されます。これは、タイトルと説明を提供するべきではないという意味ではありません。これらは、他の人があなたのステップを理解するのに役立ちます。

  • title:短くて説明的な文または半文である必要があります:生成されたIPAパス。

  • summary:これは説明の短いバージョンであり、入力の概要を簡単に説明します。 Bitriseワークフローエディターでは、ステップを表示すると、デフォルトでの概要が表示されます。

  • description:これは、ステップ入力のユーザー向けの説明です。これにより、入力のより深く、より詳細な説明が提供されます。

値のリストを含む出力

特定の出力の値のリストを提供することは絶対に可能です。これを行う場合は、出力のキーにLISTサフィックスを追加することを強くお勧めします(たとえば、 BITRISE_APK_PATH_LIST)、値が改行文字(\ n)で区切られたリストとして提供されることを期待します(たとえば、最初の値\ n2番目の値)。

値を区切るために本当に別の文字を使用する必要がない限り、このソリューションを使用してください。私たちの経験に基づくと、改行文字(\ n)は、入力値では非常にまれであるため(、、;、=または他のより一般的な区切り文字と比較して)、ユニバーサル区切り文字として非常にうまく機能します。

ステップを実行するための条件を設定する

ステップが特定のワークフローで実行されるかどうかを定義する3つのプロパティがあります:is_always_run、 is_skippable およびrun_if。これらのプロパティはすべて、 step.yml ステップのデフォルトの動作を管理するファイル、またはケースバイケースで特定のアプリのbitrise.ymlファイルに設定されます。

is_always_run:デフォルトでは、ワークフローの前のステップが失敗した場合、ステップは実行されません。ただし、 is_always_run プロパティはに設定されています true、ワークフローの前のステップのステータスに関係なく、ステップが実行されます。これは、たとえば、ビルドに関する通知を送信できるステップの場合に非常に役立ちます。失敗したビルドに関する通知を送信できます。

is_skippable:前述のように、ワークフローの前のステップが失敗した場合、ステップは実行されません。ただし、ステップの場合 is_skippable プロパティはに設定されています true、ビルドは失敗せず、特定のステップが失敗した場合でも、後続のステップが実行されます。良い例は キャッシュ:プル ステップ:アプリにプル元のビルドキャッシュがない場合、ステップは失敗しますが、ビルドが失敗する理由はありません。

run_if:ステップの実行を特定の条件に依存させたい場合は、 run_if 実行条件を定義するプロパティ。たとえば、CI環境でのみ実行されるようにステップを構成できます。詳しくはこちらをご覧ください ステップを条件付きで有効または無効にする 考えられるユースケースについてのガイド。

サブモジュールとステップの依存関係

サブモジュールを使用したり、ステップでオンデマンドでダウンロードした他のリソースを要求したりしないでください。ステップに必要なすべてのものをステップのリポジトリに含めるようにしてください。そうしないと、たとえば、ネットワークエラーまたは何らかの認証の問題が原因でステップがリソースのダウンロードに失敗した場合に、問題が発生する可能性があります。サブモジュールの場合、ステップのリポジトリのサブモジュールとして使用するのではなく、他のリポジトリのコンテンツを含める必要があります。

ただし、apt-getやbrewなど、OS依存関係マネージャーからフェッチできる依存関係を宣言することはできます。ステップ依存関係は、Bitrise CLIで使用できない場合、BitriseCLIによってインストールされます。 PATH 環境変数。

ステップはBitriseCLIを実行できる任意の環境で実行できるため、Bitriseスタックにプリインストールされていることがわかっている場合でも、使用されているすべての依存関係を一覧表示します。未使用の依存関係(たとえば、デフォルトでサンプルとして追加されたgitとwget)は、ビルド時間を浪費します。

ステップの依存関係にはツールキットの依存関係を含めないでください。BitriseCLIがそれらを自動的にインストールします。ステップがGoBitrise CLIツールキットを使用している場合、golangで記述されたステップは依存関係としてgoをリストするべきではありません。

Bitrise CLIは、Homebrewパッケージマネージャーで利用可能なステップ依存関係をインストールできます。

deps:
  brew:
  - name: cmake

ホストマシンのsources.listファイルにリストされているソースで利用可能なapt-get依存関係をインストールできます。

deps:
  apt_get:
  - name: cmake

手順では、ホストマシンで使用可能である必要があるが、簡単な方法でインストールできない依存関係を定義できます(単一のbrewまたはapt-getコマンドを使用するなど)。これらの依存関係は、 check_only 財産:

deps:
  check_only:
  - name: xcode

現在、サポートされているのは check_only 依存関係は xcode

ステップの実行中または他のステップの使用中に、他の依存関係をインストールして確認する必要があります。

EnvVarを使用してステップリポジトリ内のファイルにアクセスする

ステップリポジトリにバンドルする必要がある、ステップに必要なバイナリ、アセット、またはその他のものを保持する必要がある場合は、それらを自分の横に含めることができます。 step.yml ファイルとステップのコード。 Bitrise CLIは、と呼ばれる環境変数を自動的にエクスポートします。 BITRISE_STEP_SOURCE_DIR これにより、いつでもこれらのファイルにアクセスできます。

たとえば、次のようにアクセスできます。 .jar 次のように、ステップのリポジトリのルートにあるファイル:

$BITRISE_STEP_SOURCE_DIR/mytool.jar

ステップアイコンの追加

ステップアイコンをステップに追加できます。ワークフローエディタと 統合 ページ。必要に応じて、いくつかの要件があります。

  • その背景色は透明であってはなりません。

  • サイズ:256x256ピクセル。

  • マージン:60ピクセル。

  • フォーマット:SVG。

確認済みの手順

確認のためにステップを送信して、 確認済みのステップ、ステップアイコンを追加する必要があります。

ステップのアイコンを送信するには:

  • .svgファイルをStepLibフォークリポジトリ(STEPLIB_FORK_ROOT / Steps / YOUR_STEP_ID / assets / icon.svg)に追加します。

  • に新しいプルリクエストを作成します StepLibリポジトリ