Salesforce アプリケーションの継続的インテグレーション

Salesforce アプリケーションの開発者の皆さんに朗報です🎉 CircleCI での Salesforce アプリの構築、テスト、デプロイが簡単になりました。CircleCI 用の Salesforce インテグレーションである Salesforce SFDX CLI Orbを使用して、自動化された開発パイプラインを作成できます。

今回は、自動化された開発パイプラインを CircleCI で迅速に使用できるようにする方法を紹介します。Salesforce が提供している ebikes-lwcサンプルアプリケーションと、CircleCI の新しい Salesforce SFDX CLI orbを使用していきます。Salesforce アプリケーションの開発が初めての方は、こちらのリポジトリから学習を始められることをお勧めします。

既に独自の Salesforce アプリケーションを構築している皆さんにも役に立つ情報です。

CI パイプラインとは

初めて CircleCI を利用する皆さんには、まず継続的インテグレーションのパイプラインを使用して開発ワークフローを改善する方法についての概要をお読みになることをお勧めします。

簡単に言えば、CircleCI はコードをすばやく安全に配信するためのプラットフォームです。CircleCI パイプラインでは、アプリケーションに新機能や変更を追加し、これらをテストしたうえでデプロイします。テストに失敗した場合は、CircleCI から通知が届きます。信頼性の高いコードが完成したら、手動または自動でユーザーにデプロイすることができます。

セットアップ

パイプラインの作成に取り掛かる前に、いくつかのセットアップ作業が必要です。

最初の作業は簡単です。お使いのアカウントでDev Hub を有効化します。こうすることで、スクラッチ組織を作成し、管理することができます。スクラッチ組織とは、アプリケーションのテストに必要となる、使い捨ての安全な環境のことです。
次に、独自の自己署名 SSL 証明書と非公開鍵を作成します。Salesforce CLI で認証する場合、通常はブラウザーウィンドウを起動してログインしますが、ユーザーの介入が不要な CircleCI の CI 環境では、他の認証方法が必要になります。

CircleCI では、JWT ベースの認証を採用しています。Salesforce に CircleCI が発行した証明書を持たせ、CircleCI 側の非公開鍵で認証を行います。証明書と鍵を作成する方法については、こちらをご覧ください。
パイプラインを開始する前に、接続アプリを作成する必要があります。接続アプリを通じてクラウド環境内の Salesforce インスタンスに接続し、2 で作成した証明書を使用して JTW ベースの認証を行います。

接続アプリの作成方法については、Salesforce が公開しているこちらの手順をご覧ください。この手順では CircleCI の server.crt ファイルが Salesforce にアップロードされ、その後すぐに CircleCI にサーバーキーが追加されます。作成したアプリから入手したコンシューマーキーの値を書き留めておいてください。

ここまで来たら、次はプロジェクトの準備です。既にプロジェクトが作成されていれば、それを使用します。前述の ebikes-lwcのサンプルを複製してもかまいません。最終的に、プロジェクトは GitHub や BitBucket のような VCS プロバイダーでホスティングされます。

GitHub や BitBucket でプロジェクトがホストティングされるようになったら、パイプラインの作成を開始できます。

プロジェクトを CircleCI に追加する

プロジェクトはまだ完成していません。まだ CircleCI の設定ファイルを追加する必要があります。これは、始めに行うべき準備作業の最終段階です。

CircleCI で VCS認証を行ってログインします。ダッシュボードの [Add Projects (プロジェクトの追加)] をクリックして、現在ログインしているアカウントのプロジェクトのリストを表示します。Salesforce アプリケーションの [Set Up Project (プロジェクトのセットアップ)] をクリックします。

Salesforceプロジェクト設定画面

次のページの設定はすべて既定のままにしておきましょう。後でもう一度このページに戻ってきます。[Start Building (ビルドの開始)] をクリックします。

ビルド開始画面

すると、ジョブの失敗を示すエラーページが表示されますが、心配は要りません。まだ設定ファイルの追加も、環境変数のセットアップも終えていないのですから、想定どおりの結果です。

環境変数を追加する

新しく追加したプロジェクトに、必要な環境変数を追加しましょう。画面左側のナビゲーションバーに、CircleCI に追加したプロジェクトのリストが表示されます。Salesforce アプリケーションの横にある歯車のアイコンをクリックして、設定ページを開きます。

プロジェクトのリスト表示画面

[Build Settings (ビルド設定)] の [Environment Variables (環境変数)] をクリックします。

ビルド設定画面

ここで、認証のために 2 つの情報を追加します。

環境変数	値
SFDX_JWT_KEY	この値には、非公開の server.key ファイルの Base64 エンコードされた値が含まれます。
SFDX_CONSUMER_KEY	Salesforce の接続アプリのコンシューマーキーです。

コンシューマーキーは、前のステップで生成したものを使用します。新しい環境変数 SFDX_CONSUMER_KEYと Salesforce の値を追加するだけで完了です。

Base64 エンコードされた JWT キーを取得するには、前のステップで作成した自己署名証明書ファイルが格納されているディレクトリに移動し、base64 server.key のコマンドを入力します。Base64 エンコードされた値を取得したら、コピーしてプロジェクトの環境変数 SFDX_JWT_KEY の下に追加します。

設定ファイルを追加する

必要なセットアップはこれで完了です。これまでの手順をまとめます。

Salesforce アカウントで Dev Hub を有効にする
接続アプリを作成する
接続アプリで JWT 認証を有効にする
CircleCI にプロジェクトを追加する
必要な環境変数を追加する

ここまでの手順を完了すると、CircleCI で Salesforce による認証が可能になり、設定ファイル内で SFDX CLI を利用できるようになります。

プロジェクトリポジトリのメインディレクトリで、トップレベルの .circleci フォルダーを追加し、このフォルダーの下に config.yml ファイルを作成します。CircleCI は、リポジトリに更新がプッシュされると自動的にこのファイルを確認します。このファイルは言わば、その更新に対してどのようなアクションを実行する必要があるかを示すブループリントのようなものです。CircleCI の設定ファイルにまだ馴染みがない方は、CircleCI の入門ガイドをぜひ確認してください。

config.yml ファイルを作成したら、Salesforce SFDX CLI orb に含まれる使用例の部分に上書きコピーして、実際に使ってみましょう。

version: 2.1
 orbs:
   sfdx: circleci/salesforce-sfdx@x.y
 jobs:
   install_authenticate:
     executor: sfdx/default
     steps:
       - checkout
       - sfdx/install
       - sfdx/auth:
           defaultusername: user@email.com
       - run:
           name: Run your SFDX commands here
           command: |
             echo "You now have access to the sfdx cli and may execute commands against it. https://developer.salesforce.com/docs/atlas.en-us.sfdx_cli_reference.meta/sfdx_cli_reference/cli_reference.htm"
 workflows:
   basic-test:
     jobs:
       - install_authenticate

設定ファイルの内容

設定ファイルの内容を詳しく見ていきましょう。

version: 2.1
 orbs:
   sfdx: circleci/salesforce-sfdx@x.y

Orbs を使用するには、バージョン 2.1 の CircleCI 設定ファイルが必要です。現在、設定ファイルのバージョンはデフォルトで 2.1 に設定されていますが、将来の更新の可能性を踏まえ、明示的にバージョンを指定することをお勧めします。

Orbs スタンザで、Orb パッケージを定義してインポートします。この例では、必要なのは circleci/salesforce-sfdx Orb だけです。これを sfdx としてインポートすることで、設定ファイルのどこでも参照できるようになります。

インポートステートメントの末尾にバージョンタグ @x.y が記述されている点にも注意してください。これはプレースホルダーです。Orb レジストリページで最新のドキュメントを確認し、最新バージョンの Orb をインポートしてください。

Orbs にはセマンティックバージョニングスキームが採用されています。1.0.0 のように完全なバージョン番号を指定してインポートすることもできますが、できるだけマイナーバージョンまでの指定にとどめることをお勧めします。そうすることで、1.0 -> 1.0.1 -> 1.0.2 のように、パッチリリースが自動的に選択されます。

ジョブ

Orb のインポートステートメントの下には、jobs スタンザが記述されており、install_authenticate というジョブが 1 つ指定されています。

jobs:
   install_authenticate:

これは、設定ファイル内に手動で定義するジョブです。Orb に事前定義済みのジョブが付属している場合は、それを使ってもかまいません。

ジョブの名前はもちろん自由に指定できます。ワークフローによっては複数のジョブを指定することも少なくありません。このワークフローでは、単一のジョブで、CLI ツールをインストールし、認証する方法を示します。

Executor

CircleCI では、Windows、Mac、Linux、Docker の多岐にわたる実行環境を利用できます。ジョブを定義するとき、コマンドが実行されますが、コマンドを実行する実行環境を選択する必要があります。

Orbs では、パラメーター化された Executorの構成を定義することも可能できます。circleci/salesforce-sfdx Orb でも次のように記述されています。デフォルトの Executor を使用すると、コンパクトかつ高速で効率的な NodeJS Docker 環境が自動的に選択されます。この環境は、Salesforce アプリケーションタスクに最適です。

executor: sfdx/default

ステップ

ステップは、上記の手順で定義した環境内で順番に実行される実行可能コマンドの集合です。

 - checkout
       - sfdx/install
       - sfdx/auth:
           defaultusername: user@email.com

checkout: CircleCI ネイティブの組み込みコマンドです。リポジトリからソースコードをフェッチします。インテグレーションには必要ありませんが、通常、あらゆるプロジェクトの最初のステップになります。
sfdx/install: circleci/salesforce-sfdx Orb で提供されている Orb コマンドです。最新の CLI が収められたスタンドアロン型の tar をインストールします。version パラメーターを追加して、NPM から特定のバージョンをインストールすることもできます。詳しくは、Orb のドキュメントをご覧ください。
sfdx/auth: Circleci/salesforce-sfdx Orb で提供されている Orb コマンドです。JWT 認証を利用して、接続アプリで認証を行います。環境変数 SFDX_JWT_KEY と SFDX_CONSUMER_KEY を忘れずに設定してください。また、defaultusername もこの例のとおりに設定してください。

これで、Orb 内の他のコマンドを利用したり、追加コマンドを指定して sfdx と直接やり取りしたりできるようになります。

例

     - run:
         name: Check Auth List
         command: sfdx force:auth:list

ワークフロー

ワークフローは、どのジョブをいつ実行するかを指定できる、CircleCI の機能です。このワークフローにはジョブが 1 つしかありません。これをコミットごとに実行するので、フィルターは指定しないことにします。basic-test という名前のワークフローを作成し、install_authenticate というジョブを指定します。

 workflows:
   basic-test:
     jobs:
       - install_authenticate

Salesforce SFDX CLI Orb でできること

自動化: 事前構成済みのジョブを使用して、スクラッチ組織内で自動的にアプリケーションをビルドし、テストします。
コントリビューション: この Orb インテグレーションのオープンソースリポジトリに、機能に関するリクエストやプルリクエストをお送りください。

Salesforce 開発者の皆さんからのご意見、ご感想をお待ちしています。Orb をどのように活用しているか、Twitter で @CircleCIJapan にメンションしてぜひお聞かせください。