using-bitrise-ci

Name: using-bitrise-ci
Author: bitrise-io

github.com/bitrise-ioクラウド・DevOps5107 回インストール31 週間前に更新

using-bitrise-ci について

using-bitrise-ciは、Bitrise CIを扱うためのスキルです。プロジェクト、ビルド、`bitrise.yml`を設定する担当者向けに、MCPサーバー、API、CLIによるアクセス、ワークフロー設計、ビルドのトラブルシューティングを解説します。

主な機能

01MCP、API、CLIでのアクセス案内
02プロジェクト設定の手順
03`bitrise.yml`の構成と検証
04ワークフロー、パイプライン、ステップの設定
05ビルドのトラブルシューティング案内

活用シーン

01リポジトリをBitriseプロジェクトに登録
02CIワークフローの作成や検証
03Bitriseビルドの問題調査

MCP 対応

認証を用いた自動アクセスにBitrise MCPサーバーを利用する方法を説明し、利用可能な場合は優先するよう案内します。Bitriseを操作する別の手段としてAPIとCLIも扱います。

インストール

コマンドをコピーしてターミナルで実行します。

$npx skills add https://github.com/bitrise-io/agent-skills --skill using-bitrise-ci

インストール後、Claude Code で/using-bitrise-ciを入力して読み込まれたか確認します。

同梱ファイルpipelines.md

詳細

Bitrise CI の使用

自動化されたアクセス

認証

Bitrise を自動化された方法（API、MCP など）で利用するには、アクセストークンが必要です。ユーザーは個人用またはワークスペース用のアクセストークンを作成できます。安全に保管してください。

MCP サーバー

Bitrise MCP サーバーは https://github.com/bitrise-io/bitrise-mcp でオンライン利用できるほか、ローカルで実行することもできます。Authorization: Bearer {token} ヘッダーを使用したトークン認証が必要です。MCP サーバーが利用可能な場合は、API やその他のツールよりも優先して使用してください。

API

Bitrise REST API を使用すると、さまざまな Bitrise リソースを管理できます。詳細なリファレンスはこちらで確認できます。API では、Authorization: {PAT} ヘッダーを使用した PAT による認証が必要です（Bearer は付けません）。

CLI

Bitrise CLI はローカル環境での作業に便利です。Bitrise のリソースとはやり取りしませんが、bitrise.yml の編集や検証に役立ち、ワークフローをローカルで実行できます。Mac と Linux に対応しています。

インストールするには、brew install bitrise を使用するか、その他の方法についてはリリースページを確認してください。

ローカル実行では、作業ディレクトリのルートに bitrise.yml が必要です。機密性の高い入力を含む .bitrise.secrets.yml を任意で配置できます。

一般的なコマンド：

# Output the list of available commands
bitrise help

# Start local workflow editor UI
bitrise :workflow-editor

# Validate bitrise.yml
bitrise validate -c {config_path}

# List available workflows
bitrise workflows

# Run a workflow locally
bitrise run {workflow_id}

基本概念

ワークスペースは、プロジェクトとそのメンバーを整理する最上位の単位です。

プロジェクトは、DevOps プロセスを格納するものです。プロジェクトには、Git リポジトリを基にビルドを実行する CI 設定（ツールによっては アプリ とも呼ばれます）を含めることができます。

ステップは個々のビルドタスクで、設定や他のステップとの連携に使用する入力と出力を設定できます。ステップはステップライブラリで確認できます。

ステップバンドルは、重複を減らすために複数のワークフローに含められる、再利用可能なステップのコレクションです。

ワークフローは、ランナーマシン上で順番に実行される一連のステップです。ワークフローをトリガーするとビルドが開始され、ログと、任意でダウンロード可能なファイル（アーティファクト）やテスト結果が生成されます。

ビルドは、特定の OS バージョンと追加のソフトウェアツールを組み合わせたスタック用の仮想マシン上で、要求するハードウェアリソースを表す指定のマシンタイプを使用して実行されます。利用可能なマシンタイプは、選択したスタックによって異なります。選択肢を取得するには、bitrise:list_available_stacks ツールまたは /available-stacks API エンドポイントを使用してください。

パイプラインを使用すると、依存関係を設定したワークフローから、並列実行や順次実行、シャーディング、ファイル共有を含む複雑なプロセスを作成できます。

コンテナー（実行用およびサービス用）を使用すると、ステップやステップバンドルを分離された Docker 環境で実行したり、バックグラウンドの Docker サービスと並行して実行したりできます。Linux 専用です。macOS スタックではサポートされていません。

環境変数（略して env）は、さまざまなレベルで定義できる設定変数で、入力として各コンポーネントに渡されます。ビルド中に利用できる組み込み env については、このページを参照してください。

シークレットは、値が保護された env です。暗号化して保存され、ビルドログではマスクされます。

これらのコンポーネントは、Git リポジトリまたは Bitrise のウェブサイトに保存されている bitrise.yml ファイルで設定します。

プロジェクトの作成

前提条件

ソースはオンラインの git リポジトリとして利用できる必要があります。リポジトリへのアクセスは、サービスユーザーまたは GitHub App 経由で設定できます。ユーザーはまず UI からプロバイダーに接続する必要があります。

ワークフロー

プロセス中に発生したエラーは必ずユーザーに伝え、すべて正常に進んだと思わせないようにしてください。重要な機能が動作していない可能性があります。

次のチェックリストを使用してください。

ソースリポジトリを特定する
プロジェクトを追加するワークスペースを特定する
デフォルトブランチを選択し、リモートリポジトリに存在することを確認する。
アプリを登録する
リポジトリがプライベートの場合、SSH キーを登録する
アプリのセットアップを完了する
bitrise.yml を更新する。まず有効なファイルであることを確認してください。

bitrise:register_app ツールまたは /apps/register API エンドポイントを使用してアプリを登録します。特に指示がない限り、プロジェクトはプライベートとして作成してください。

bitrise:register_ssh_key ツールまたは /apps/{app-slug}/register-ssh-key API エンドポイントを使用してSSH キーを登録できます。前の手順で受け取った app_slug を使用してください。

bitrise:finish_bitrise_app ツールまたは /apps/{app-slug}/finish API エンドポイントを使用してアプリのセットアップを完了します。プロジェクトの種類（デフォルトは other）と、ビルドの実行に使用するスタックを指定してください。

bitrise.yml の更新：bitrise.yml が Bitrise に保存されている場合は、その内容をアップロードしてください（新しく作成したアプリではこれがデフォルトです。既存のアプリについては、/apps/{app-slug}/bitrise.yml/config API リクエストを使用して確認できます）。それ以外の場合、bitrise.yml はソースリポジトリでバージョン管理されているため、この手順は省略できます。

詳細なドキュメントはこちらをご覧ください。

CLI からプロジェクトを対話的に追加する

ユーザーが希望する場合は、bitrise-add-new-project ツールを使用できます。この操作には Bitrise アカウントと、チェックアウト済みの git リポジトリが必要です。

bitrise.yml の操作

デフォルトでは、bitrise.yml は Bitrise サーバーに保存され、ソースリポジトリからは読み込まれません。リポジトリへの保存に切り替えることで、バージョン管理やレビューなどが可能になります。これは /apps/{app-slug}/bitrise.yml/config API エンドポイントから設定できます。

ベストプラクティス

まず必ず計画を立てます。ワークフローを使って全体のプロセスを設計し、その後にステップへ分割します。
パイプライン、ワークフロー、ステップバンドル、その他のリソースには、明確で内容がわかる名前を付けます。
API キー、トークン、パスワード、証明書のパスフレーズにはシークレット環境変数を使用します。アプリ名、バンドル ID、バージョン番号、機能フラグには通常の環境変数を使用します。
クラウドビルド用のシークレットは Bitrise の Web UI に保存します。
.bitrise.secrets.yml は絶対にコミットしないでください。

構造

JSON スキーマについては Schemastore を、完全なリファレンスについてはこちらのページをご覧ください。

format_version は必須フィールドで、設定スキーマのバージョンを表します（最新機能には "25" を使用してください）。
default_step_lib_source も必須で、別途指定されていない場合にステップを読み込む場所を表します。値には https://github.com/bitrise-io/bitrise-steplib.git を使用してください。
containers は、ステップおよびステップバンドルで利用できる Docker 実行コンテナーとサービスコンテナーを定義します（Linux のみ）。
step_bundles、workflows、pipelines には、上記で説明したエンティティを列挙します（ID をキーとするマップ形式）。

app を使って、アプリレベルの環境変数を定義できます。

app:
  envs:
    - PROJECT_NAME: MyApp
    - BUNDLE_ID: com.example.myapp
    - VERSION: 1.0.0

Bitrise でビルドを実行するには、meta ブロックが必須です。
```
meta:
  bitrise.io:
    stack: linux-docker-android-22.04
```

ワークフローの構築

ワークフローには、任意の設定や条件を含むステップのリストが含まれます。

最も一般的な順序は、ソースの取得 -> ビルド -> テスト -> 公開またはデプロイ です。
リポジトリからソースを取得するには、activate-ssh-key ステップと git-clone ステップでワークフローを開始します。
特定の組み込みステップでは、テスト結果が自動的に報告されます。それ以外のツールでは、結果を変換するために custom-test-results-export が必要です。また、レポート用に結果を Bitrise にアップロードするには deploy-to-bitrise-io が必要です。詳細はこちらをご覧ください。
パフォーマンス向上のため、ビルド間で依存関係をキャッシュできます。一般的なパッケージマネージャーには専用のキャッシュステップがあります。それ以外の場合は、手動で設定する必要があります。詳細はこちらをご覧ください。

例：

format_version: "25"
meta:
  bitrise.io:
    stack: linux-docker-android-22.04
workflows:
  ci:
    steps:
    - activate-ssh-key@4:
        run_if: '{{getenv "SSH_RSA_PRIVATE_KEY" | ne ""}}'
    - git-clone@8: {}
    - restore-cache@2:
        inputs:
        - key: cache-key-{{ .Branch }}
    - android-unit-test@1:
        inputs:
        - project_location: $PROJECT_LOCATION
        - variant: $VARIANT
    - android-build-for-ui-testing@0:
        inputs:
        - variant: $VARIANT
        - module: $MODULE
    - virtual-device-testing-for-android@1:
        inputs:
        - test_type: instrumentation
    - android-lint@0:
        inputs:
        - variant: "$VARIANT"
    - android-build@1:
        inputs:
        - project_location: "$PROJECT_LOCATION"
        - module: "$MODULE"
        - variant: "$VARIANT"
    - deploy-to-bitrise-io@2: {}
    - slack@3:
        inputs:
        - channel: "#build-notifications"
        - webhook_url: "$SLACK_WEBHOOK"
    - save-cache@1:
        inputs:
        - key: cache-key-{{ .Branch }}
    triggers:
      push:
      - branch: '*'
      pull_request:
      - target_branch: 'main'
      - comment: 
          regex: '.*trigger (b|B)itrise.*'

ステップの使用

他のソースよりも公式ステップを優先してください。あるアクション専用のステップがない場合は、script を使用します。
```
- script@1:
    title: Print build info
    inputs:
    - content: |
        echo "Building branch: $BITRISE_GIT_BRANCH"
```
ステップを見つけるには、bitrise:step_search ツールまたは /search-steps エンドポイントを使用します。
ステップを指定する際は、メジャーバージョンに固定してください（例：git-clone@8）。これにより、破壊的変更を防ぎながらバグ修正を適用できます。ステップ検索ツールを使って確認してください。
ステップの入力に関する情報を取得するには、bitrise:step_inputs ツールまたは /step-inputs エンドポイントを使用します。

条件付きステップ実行

条件に基づいてステップの実行を制御するには、run_if を使用します。

- slack@3:
    run_if: .IsBuildFailed
    inputs:
      - webhook_url: $SLACK_WEBHOOK_URL
      - text: "Build failed on ${BITRISE_GIT_BRANCH}"

使用可能な式：.IsBuildFailed、.IsCI、.IsPR、{{getenv "VAR" | ne ""}}

ステップバンドル

同じステップの並びが複数のワークフローに現れる場合は、ステップバンドルに抽出してワークフローを最適化します。ステップバンドルは bundle:: プレフィックスを付けて参照でき、ステップと同様に入力／出力を設定できます。ステップバンドルはネストできます。

例：

step_bundles:
  install_deps:    
    inputs:
    - cache_key: "npm-cache-{{ checksum "package-lock.json" }}"
    - npm_command: install
    steps:    
    - restore-cache@2:
        inputs:
        - key: $cache_key
    - npm@1:
        inputs: 
        - command: $npm_command
workflows:
  ci:
    steps:
    - git-clone@8: {}
    - bundle::install_deps:        
        inputs:
        - cache_key: "npm-cache"
    - deploy-to-bitrise-io@2: {}

新しいワークフローを作成する際は、廃止された before_run または after_run の構文ではなく、必ずステップバンドルを優先してください。既存のワークフローではそのまま使用してください。

Docker コンテナ

Docker コンテナを使うと、ステップやステップバンドルを隔離された Docker 環境内、またはバックグラウンドサービスと並行して実行できます。Linux のみ対応しており、macOS スタックではサポートされていません。

コンテナは containers キーの下、最上位で定義し、個々のステップまたはステップバンドルから参照します。

実行コンテナ

type: execution を使って、特定の Docker イメージ内でステップを実行します。

containers:
  node-21:
    type: execution
    image: node:21.6
    ports:
      - 3000:3000
    envs:
      - NODE_ENV: ci
    credentials:
      username: $DOCKER_USERNAME
      password: $DOCKER_PASSWORD

ステップから execution_container を使って参照します（文字列の省略形式、またはオプションを設定するオブジェクト形式）。

workflows:
  ci:
    steps:
      - script@1:
          execution_container: node-21          # string shorthand: reuse existing instance
          inputs:
            - content: node --version
      - script@1:
          execution_container:
            node-21:
              recreate: true                    # object form: discard and start fresh
          inputs:
            - content: node --version

主な動作：

最も近い定義が優先される継承：ステップは、まず自身の execution_container 定義を使用し、次に親ステップバンドル、さらにその親の定義を使用します。各ステップで有効になる実行コンテナは 1 つだけです。
参照元での上書き：ステップバンドルを参照する際、呼び出し側で execution_container を設定すると、バンドル定義内のコンテナが上書きされます。上書きの優先順位は、ステップレベル > バンドルの呼び出し側 > バンドル定義です。
```
step_bundles:
  run-tests:
    execution_container: ruby   # bundle definition default
    steps:
    - script@1:
        inputs:
        - content: bundle exec rspec
workflows:
  ci:
    steps:
    - bundle::run-tests:
        execution_container: ruby-3-3   # call-site overrides the definition
```
ファイル共有：/bitrise、/root/.bitrise、/tmp はすべてのコンテナとホスト間で共有されます。デフォルトの作業ディレクトリは /bitrise/src です。
コンテナの再利用：デフォルトでは、コンテナはステップ間で再利用されます。新しいインスタンスを強制するには、オブジェクト形式で recreate: true を使用します（上記の例を参照）。

サービスコンテナ

type: service を使用すると、バックグラウンドの Docker サービス（データベース、HTTP サーバーなど）を Steps と一緒に実行できます。

containers:
  postgres:
    type: service
    image: postgres:16
    ports:
      - 5432:5432
    envs:
      - POSTGRES_PASSWORD: $POSTGRES_PASSWORD
    credentials:
      username: $DOCKER_USERNAME
      password: $DOCKER_PASSWORD
      server: us-central1-docker.pkg.dev
    options: >-
      --health-cmd pg_isready
      --health-interval 10s

service_containers を使って Step から参照します（文字列の省略形式とオブジェクト形式を組み合わせられます）。

workflows:
  ci:
    steps:
      - script@1:
          service_containers:
            - postgres:
                recreate: true    # object form: discard and start fresh
            - redis               # string shorthand: reuse existing instance

主な動作：

加算的な継承：サービスコンテナは、すべての祖先 Step バンドル階層から累積されます。実行コンテナとは異なり、最も近い親によって上書きされることはありません。
使用側での上書き：バンドルの呼び出し元で service_containers を設定すると、バンドル定義内で定義されたサービスコンテナが上書きされます。
ネットワーク：すべてのサービスコンテナは bitrise Docker ネットワークを共有します。
- Step が実行コンテナを使用する場合：コンテナ ID をホスト名としてサービスにアクセスします（例：http://postgres:5432）。
- Step がホスト上で直接実行される場合：localhost 経由でサービスにアクセスします（例：http://localhost:5432）。

認証情報

Docker レジストリの認証情報を Secrets として保存し、credentials ブロックで参照します（username、password、および Docker Hub 以外のレジストリでは任意で server）。

サポートされていないオプション

Docker オプションの --network、--volume（-v）、--entrypoint は options フィールドではサポートされていません。

レガシーな `with:` グループ

古い構文では、steps リスト内の with: ブロックに container（文字列）および services（文字列のリスト）プロパティを指定します。新しい設定では使用しないでください。同じ bitrise.yml 内で、step ベースの execution_container／service_containers 構文と併用することはできません。

カスタム Docker イメージのビルド

docker-build-push step を使用すると、ワークフロー中にカスタムイメージをビルドしてプッシュでき、そのイメージを後続のビルドでコンテナイメージとして参照できます。

パイプラインのビルド

依存関係、並列処理、シャーディング、アーティファクト共有を備えた複数ワークフローのプロセスを設計します。詳細は pipelines.md を参照してください。

新しいパイプラインを作成する場合は、常に depends_on による明示的な依存関係を優先してください。ステージは、すでにステージを含む既存のパイプラインを編集する場合にのみ使用してください。

トリガー

ワークフローとパイプラインでは、ビルドを開始するソースリポジトリのイベント条件を指定できます。

トリガーは、各パイプラインまたはワークフローに設定できます。複数のトリガーを追加でき、それぞれに複数の条件を指定できます。一致するトリガー項目があるすべてのパイプライン／ワークフローが開始されます。

例：

workflows:
  workflow-tests:
    triggers:
      push:
      # Exact match
      - branch: "release" 
pipelines:
  pipeline-build:
    workflows: {}
    triggers:
      push: 
      # Using a wildcard
      - branch: "*"
      # Multiple conditions
      - branch: release
        changed_files: path/to/library-a/.*
      tag:
      # Regex
      - name:
          regex: '^\d\.\d\.\d$'

レガシー形式

トップレベルの trigger_map タグには、順序付きの項目リストが含まれます。受信イベントに対して、最初に一致した項目によって、指定されたパイプライン／ワークフローでビルドが開始されます。 新しい bitrise.yml ファイルを作成する場合は、常に新しい形式を優先し、すでに存在する場合にのみ trigger_map を使用してください。

モジュラー YAML

エンタープライズプランでは、組織やコードの構造を反映し、競合を減らすために、bitrise.yml を複数のファイルに分割できます。詳細はこちらを参照してください。

例：

format_version: "25"
include:
  - _workflows/shared.yml
  - _workflows/ios.yml
  - _workflows/android.yml

結果の検証

次のワークフローを使用します。

YML ファイルを検証します。ファイルが大きい場合は、インストール済みであれば CLI を使用するか、ファイルを cURL にストリーミングして API を使用します。

bitrise validate -c bitrise.yml
bitrise:validate_bitrise_yml MCP ツール
/validate-bitrise-yml API エンドポイント

検証に失敗した場合：
- エラーメッセージを注意深く確認します
- 問題を修正します
- もう一度検証を実行します
検証に成功した場合にのみ続行してください
可能であればローカルでテストします：bitrise run {workflow_id}

ビルドのトラブルシューティング

ビルドログを確認します。
失敗したステップ（複数ある場合があります）を特定し、その出力からエラーを探します。
失敗の原因が設定の問題（無効なスタック、順序の誤りなど）なのか、ソース（テスト、リンティングなど）なのかを判断します。
設定の問題の場合：失敗したステップは削除しないでください。適切なステップが使用されていることを確認し、その設定を修正します。必要に応じて、確認の質問をしてください。一般に、設定の無関係な部分は編集または削除しないでください。

便利なリンク

Bitrise のドキュメント：https://docs.bitrise.io/
Step Library：https://github.com/bitrise-steplib 各ステップはここにあるリポジトリです。
Bitrise CLI（GitHub）：https://github.com/bitrise-io/bitrise
bitrise.yml リファレンス：https://docs.bitrise.io/en/bitrise-ci/references/configuration-yaml-reference.html
スタックのドキュメント：https://bitrise.io/stacks

Markdown 対応

ログインしてコメント

基本情報

作者: bitrise-io
リポジトリ: bitrise-io/agent-skills
カテゴリ: クラウド・DevOps
インストール数: 107
GitHub スター: 5

問題を報告