sf-deploy

デプロイオーケストレーター

Salesforce のデプロイを専門としています。エラー処理と依存関係の解決を行いながら、複数ステップのデプロイを管理します。

デプロイワークフロー

1. デプロイ前のチェック

# Verify org connection
sf org display --target-org myOrg

# Check what will be deployed
sf project deploy preview -d force-app/

# Validate without deploying
sf project deploy start -d force-app/ --dry-run --target-org myOrg

2. package.xml の生成

# From org (full manifest)
sf project generate manifest --from-org myOrg --output-dir manifest/

# From local source
sf project generate manifest -d force-app/ --output-dir manifest/

3. デプロイ順序（依存関係のあるものを先に）

依存関係による失敗を避けるため、次の順序でデプロイします。

1. カスタムオブジェクトと項目 — コードから参照する前にスキーマが存在している必要があります
2. カスタム表示ラベルとカスタムメタデータ — Apex とフローから参照されます
3. 権限セットとカスタム権限 — バイパスロジックに必要です
4. Apex クラス — サービスクラス、セレクター、ユーティリティを先にデプロイします
5. Apex トリガー — ハンドラークラスに依存します
6. フロー — Apex アクションを参照する場合があります
7. LWC — Apex コントローラーにワイヤリングする場合があります
8. レイアウト、FlexiPages、プロファイル — 上記のすべてを参照します

4. デプロイコマンド

# Deploy specific directory
sf project deploy start -d force-app/main/default/classes/ --target-org myOrg

# Deploy with specific tests
sf project deploy start -d force-app/ --test-level RunSpecifiedTests --tests MyClassTest,MyOtherClassTest --target-org myOrg

# Deploy with all tests (production)
sf project deploy start -d force-app/ --test-level RunLocalTests --target-org myOrg

# Deploy specific metadata
sf project deploy start -m ApexClass:MyClass,ApexClass:MyClassTest --target-org myOrg

# Quick deploy (after successful validation)
sf project deploy quick --job-id <validationId> --target-org myOrg

5. 差分デプロイ

CI/CD では、変更されたファイルのみをデプロイします。

# Using sfdx-git-delta
sfdx sgd:source:delta --from origin/main --to HEAD --output delta/
sf project deploy start -d delta/force-app/ --target-org myOrg

スクラッチ組織のワークフロー

# Create scratch org from definition file
sf org create scratch -f config/project-scratch-def.json -a scratch1 -d 30

# Create from org shape (clones source org config)
sf org create scratch --source-org prodOrg -a scratch1

# Delete scratch org
sf org delete scratch -o scratch1 --no-prompt

パッケージ開発

# Create unlocked package
sf package create --name "My Package" --package-type Unlocked --path force-app

# Create package version
sf package version create --package "My Package" --installation-key test1234 --wait 10

# Install package in target org
sf package install --package 04t... --target-org myOrg --wait 10

• Unlocked Packages：組織に依存せず、名前空間が固定されず、インストール後も編集できます
• 2GP Managed：名前空間が固定され、IP が保護され、AppExchange で配布できます

破壊的変更

<?xml version="1.0" encoding="UTF-8"?>
<Package xmlns="http://soap.sforce.com/2006/04/metadata">
    <types>
        <members>OldClass</members>
        <name>ApexClass</name>
    </types>
    <version>62.0</version>
</Package>

• destructiveChangesPre.xml — デプロイ前に削除します（先に依存関係を削除します）
• destructiveChangesPost.xml — デプロイ後に削除します（置き換えられたコンポーネントをクリーンアップします）
• 次のコマンドでデプロイします：sf project deploy start -d force-app/ --post-destructive-changes destructiveChangesPost.xml

認証方法

方法	用途	コマンド
Web ログイン	対話型／開発	sf org login web
JWT Bearer	CI/CD（ヘッドレス）	sf org login jwt --client-id ... --jwt-key-file ...
SFDX Auth URL	CI/CD（より簡単）	sf org login sfdx-url --sfdx-url-file authUrl.txt
Device Flow	ヘッドレス（証明書なし）	sf org login device

Salesforce Code Analyzer

# Run static analysis
sf scanner run --target force-app/ --format csv --outfile results.csv

# Run with specific rules
sf scanner run --target force-app/ --category "Security,Best Practices"

テストレベルガイド

レベル	使用する場面	コマンドフラグ
NoTestRun	本番以外、メタデータのみ	--test-level NoTestRun
RunSpecifiedTests	影響を受けるテストが判明している場合	--test-level RunSpecifiedTests --tests MyTest
RunLocalTests	本番環境へのデプロイ	--test-level RunLocalTests
RunAllTestsInOrg	完全な検証	--test-level RunAllTestsInOrg

エラーの診断

よくあるデプロイエラー

エラー	原因	解決方法
Entity not found: CustomObject__c	依存関係がありません	先にカスタムオブジェクトをデプロイします
Dependent class is invalid	依存先のコンパイルエラー	先に依存先のクラスを修正します
Code coverage is below 75%	テストが不十分です	sf-test スキルを実行してテストを生成します
Component not found: c:myComponent	LWC の依存関係がありません	先に LWC をデプロイしてから FlexiPage をデプロイします
Test failure: System.AssertException	テストが誤ったデータを想定しています	テストのアサーションを修正します
FIELD_CUSTOM_VALIDATION_EXCEPTION	入力規則がテストデータをブロックしています	入力規則を通過するようにテストデータを更新します
INSUFFICIENT_ACCESS_ON_CROSS_REFERENCE_ENTITY	共有または権限の問題です	プロファイル／権限セットのデプロイを確認します

失敗の診断

# Check deploy status
sf project deploy report --job-id <jobId>

# Get detailed error info
sf project deploy resume --job-id <jobId>

CI/CD パイプライン（GitHub Actions）

name: Salesforce CI/CD
on:
  pull_request:
    branches: [main]
  push:
    branches: [main]

jobs:
  validate:
    runs-on: ubuntu-latest
    if: github.event_name == 'pull_request'
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
      - run: npm install @salesforce/cli -g
      - name: Authenticate
        run: sf org login jwt --client-id ${{ secrets.SF_CLIENT_ID }} --jwt-key-file server.key --username ${{ secrets.SF_USERNAME }} --instance-url ${{ secrets.SF_INSTANCE_URL }} --alias ci-org
      - name: Validate
        run: sf project deploy start -d force-app/ --dry-run --test-level RunLocalTests --target-org ci-org

  deploy:
    runs-on: ubuntu-latest
    if: github.ref == 'refs/heads/main' && github.event_name == 'push'
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
      - run: npm install @salesforce/cli -g
      - name: Authenticate
        run: sf org login jwt --client-id ${{ secrets.SF_CLIENT_ID }} --jwt-key-file server.key --username ${{ secrets.SF_USERNAME }} --instance-url ${{ secrets.SF_INSTANCE_URL }} --alias prod-org
      - name: Deploy
        run: sf project deploy start -d force-app/ --test-level RunLocalTests --target-org prod-org

注意点

• プロファイルはマージ競合の原因になります — デプロイ可能な権限には権限セットを優先します
• 破壊的変更はロールバックできません — 必ず事前に検証してください
• クイックデプロイの検証は10 日後に期限切れになります
• スクラッチ組織の有効期限が切れると、ソース追跡がリセットされます
• パッケージの依存関係は依存順にインストールする必要があります
• コンポーネント間の API バージョンの不一致により、気付かないままデプロイに失敗する場合があります
• RunLocalTests は管理パッケージのテストをスキップします — RunAllTestsInOrg はそれらも含みます
• Sandbox の更新では、手動で行った設定変更は保持されません

ロールバック戦略

Salesforce にはネイティブのロールバック機能がありません。次の方法で対処します。

1. デプロイ前に必ず検証（--dry-run）します
2. 以前のバージョンを git に保持します。ロールバックするには、以前のコミットをデプロイします
3. 破壊的変更を行う場合は、destructiveChangesPost.xml を用意します
4. 本番環境へのデプロイ前に、スクラッチ組織／サンドボックスを使ってテストします

参考資料

• デプロイパターン — スクラッチ組織、パッケージ、破壊的変更、サンドボックスの種類、Code Analyzer、sfdx-git-delta、認証方法、DevOps Center

ワークフロー

1. 組織の認証と接続を確認します
2. デプロイが必要なものを分析します
3. 依存関係を解決し、デプロイ順序を決定します
4. デプロイを検証します（ドライラン）
5. 適切なテストレベルでデプロイします
6. デプロイ状況を監視します
7. エラーを診断して修正します
8. デプロイが成功したことを確認します