awesome-copilot/instructions/azure-devops-pipelines.instructions_ja.md

description	applyTo
Azure DevOps Pipeline YAMLファイルのベストプラクティス	**/azure-pipelines.yml, **/azure-pipelines*.yml, **/*.pipeline.yml

Azure DevOps Pipeline YAML ベストプラクティス

一般的なガイドライン

• 適切なインデント（2スペース）でYAML構文を一貫して使用する
• パイプライン、ステージ、ジョブ、ステップには常に意味のある名前と表示名を含める
• 適切なエラーハンドリングと条件付き実行を実装する
• 変数とパラメーターを使用してパイプラインを再利用可能で保守しやすくする
• サービス接続と権限について最小権限の原則に従う
• トラブルシューティングのための包括的なロギングと診断を含める

パイプライン構造

• より良い視覚化と制御のため、複雑なパイプラインはステージを使用して整理する
• 関連するステップをグループ化し、可能な場合は並列実行を有効にするためジョブを使用する
• ステージとジョブ間の適切な依存関係を実装する
• 再利用可能なパイプラインコンポーネントにテンプレートを使用する
• パイプラインファイルを焦点を絞ったモジュール形式に保つ - 大きなパイプラインは複数のファイルに分割する

ビルドのベストプラクティス

• 一貫性のため、特定のエージェントプールバージョンとVMイメージを使用する
• ビルドパフォーマンスを向上させるために依存関係（npm、NuGet、Mavenなど）をキャッシュする
• 意味のある名前と保持ポリシーで適切な成果物管理を実装する
• バージョン番号とビルドメタデータにビルド変数を使用する
• コード品質ゲート（リンティング、テスト、セキュリティスキャン）を含める
• ビルドが再現可能で環境に依存しないことを確保する

テスト統合

• ビルドプロセスの一部として単体テストを実行する
• 標準形式（JUnit、VSTestなど）でテスト結果を公開する
• コードカバレッジレポートと品質ゲートを含める
• 適切なステージで統合テストとエンドツーエンドテストを実装する
• 利用可能な場合はテスト影響分析を使用してテスト実行を最適化する
• テスト失敗時に迅速にフェイルして速やかなフィードバックを提供する

セキュリティの考慮事項

• 機密設定とシークレットにはAzure Key Vaultを使用する
• 変数グループで適切なシークレット管理を実装する
• 必要最小限の権限でサービス接続を使用する
• セキュリティスキャン（依存関係の脆弱性、静的分析）を有効にする
• 本番デプロイメントに承認ゲートを実装する
• サービスプリンシパルの代わりに可能な場合はマネージドIDを使用する

デプロイメント戦略

• 適切な環境昇格（開発 → ステージング → 本番）を実装する
• 適切な環境ターゲティングでデプロイメントジョブを使用する
• 適切な場合はブルーグリーンまたはカナリアデプロイメント戦略を実装する
• ロールバックメカニズムとヘルスチェックを含める
• 一貫したデプロイメントのためにInfrastructure as Code（ARM、Bicep、Terraform）を使用する
• 環境ごとの適切な構成管理を実装する

変数とパラメーター管理

• パイプライン間で共有される構成には変数グループを使用する
• 柔軟なパイプライン実行のためにランタイムパラメーターを実装する
• ブランチや環境に基づく条件付き変数を使用する
• 機密変数をセキュアにし、シークレットとしてマークする
• 変数の目的と期待される値を文書化する
• 複雑な変数ロジックには変数テンプレートを使用する

パフォーマンス最適化

• 適切な場合は並列ジョブとマトリクス戦略を使用する
• 依存関係とビルド出力の適切なキャッシング戦略を実装する
• 完全な履歴が不要な場合はGit操作にシャロークローンを使用する
• マルチステージビルドとレイヤーキャッシングでDockerイメージビルドを最適化する
• パイプラインパフォーマンスを監視しボトルネックを最適化する
• パイプラインリソーストリガーを効率的に使用する

監視と可観測性

• パイプライン全体で包括的なロギングを含める
• デプロイメント追跡にAzure MonitorとApplication Insightsを使用する
• 失敗と成功に対する適切な通知戦略を実装する
• デプロイメントヘルスチェックと自動ロールバックトリガーを含める
• パイプライン分析を使用して改善機会を特定する
• パイプラインの動作とトラブルシューティング手順を文書化する

テンプレートと再利用性

• 一般的なパターンのためのパイプラインテンプレートを作成する
• 完全なパイプライン継承にはextendsテンプレートを使用する
• 再利用可能なタスクシーケンスにはステップテンプレートを実装する
• 複雑な変数ロジックには変数テンプレートを使用する
• 安定性のためテンプレートを適切にバージョン管理する
• テンプレートパラメーターと使用例を文書化する

ブランチとトリガー戦略

• 異なるブランチタイプに適切なトリガーを実装する
• 関連ファイルが変更された場合のみビルドをトリガーするパスフィルターを使用する
• main/masterブランチの適切なCI/CDトリガーを設定する
• コード検証にプルリクエストトリガーを使用する
• メンテナンスタスクにスケジュールされたトリガーを実装する
• マルチリポジトリシナリオでリソーストリガーを検討する

構造例

# azure-pipelines.yml
trigger:
  branches:
    include:
      - main
      - develop
  paths:
    exclude:
      - docs/*
      - README.md

variables:
  - group: shared-variables
  - name: buildConfiguration
    value: 'Release'

stages:
  - stage: Build
    displayName: 'ビルドとテスト'
    jobs:
      - job: Build
        displayName: 'アプリケーションビルド'
        pool:
          vmImage: 'ubuntu-latest'
        steps:
          - task: UseDotNet@2
            displayName: '.NET SDKを使用'
            inputs:
              version: '8.x'
          
          - task: DotNetCoreCLI@2
            displayName: '依存関係の復元'
            inputs:
              command: 'restore'
              projects: '**/*.csproj'
          
          - task: DotNetCoreCLI@2
            displayName: 'アプリケーションビルド'
            inputs:
              command: 'build'
              projects: '**/*.csproj'
              arguments: '--configuration $(buildConfiguration) --no-restore'

  - stage: Deploy
    displayName: 'ステージングへデプロイ'
    dependsOn: Build
    condition: and(succeeded(), eq(variables['Build.SourceBranch'], 'refs/heads/main'))
    jobs:
      - deployment: DeployToStaging
        displayName: 'ステージング環境へデプロイ'
        environment: 'staging'
        strategy:
          runOnce:
            deploy:
              steps:
                - download: current
                  displayName: 'ドロップ成果物をダウンロード'
                  artifact: drop
                - task: AzureWebApp@1
                  displayName: 'Azure Web Appへデプロイ'
                  inputs:
                    azureSubscription: 'staging-service-connection'
                    appType: 'webApp'
                    appName: 'myapp-staging'
                    package: '$(Pipeline.Workspace)/drop/**/*.zip'

避けるべき一般的なアンチパターン

• YAMLファイルに機密値を直接ハードコーディングすること
• 不要なビルドを引き起こす過度に広範なトリガーを使用すること
• 単一ステージでビルドとデプロイメントロジックを混在させること
• 適切なエラーハンドリングとクリーンアップを実装しないこと
• アップグレード計画なしに非推奨のタスクバージョンを使用すること
• 保守が困難なモノリシックなパイプラインを作成すること
• 明確性のために適切な命名規則を使用しないこと
• パイプラインセキュリティのベストプラクティスを無視すること