トラブルシューティング ガイド

  • 5 分

最適な移行計画でもサポートが必要です。 このユニットでは、大規模なファイル エラーやマネキンの属性から壊れた作業項目のリンクや統合エラーまで、移行後の一般的な問題をトラブルシューティングするための構造化されたガイドを提供します。 必要に応じ、高速復旧のための CLI コマンド、スクリプト、ロールバック ガイダンスを取得します。

このユニットでは、次の内容について説明します。

  • 大きなファイル サイズ、LFS、リポジトリの肥大化に関する問題を診断して修正する方法
  • マネキン属性の問題をすばやく解決する方法
  • Azure Boards と Azure Pipelines の接続をトラブルシューティングする方法
  • 緊急時に移行されたリポジトリを安全にロールバックするタイミングと方法

リポジトリのサイズと大きなファイルの問題

Symptoms

  • 移行のタイムアウト
  • ファイル>100MBのプッシュがブロックされました。
  • 低速クローン

診断する

# Overall size and hotspots
git-sizer --verbose

# Find blobs >50MB in history
git rev-list --objects --all | \
git cat-file --batch-check='%(objecttype) %(objectname) %(objectsize) %(rest)' | \
awk '/^blob/ {if ($3 > 52428800) print $3/1024/1024 " MB " $4}' | sort -rn | head

Git LFS を使用した修復

git lfs install
git lfs track "*.{zip,jar,exe,msi,dll,mp4,pdf}"
git add .gitattributes && git commit -m "Configure Git LFS"
git lfs migrate import --above=50MB --everything
git lfs ls-files

認証とアクセス許可の失敗

Symptoms

  • アクセスが拒否されました。403 秒、統合に失敗しました

チェック

# GitHub token
gh auth status

# Azure DevOps token
curl -u :$ADO_PAT "https://dev.azure.com/$ADO_ORG/_apis/projects?api-version=6.0"

解決策

  • GitHub PAT: repo, admin:repo_hook, read:org (必要に応じて admin:org), workflow
  • ADO PAT: ビルド (読み取り)、コード (読み取り)、プロジェクト & チーム (読み取り)、サービス接続 (管理)、作業項目 (読み取り/書き込み)、"すべての組織"

マネキンの解像度

Symptoms

  • "Mannequin" に関連する PR/コミット

解決策

cat > user-mapping.csv << EOF
mannequin-login,target-user
john-mannequin,john.doe
EOF

gh ado2gh reclaim-mannequin \
--github-org "$GITHUB_ORG" \
--csv-file user-mapping.csv

Azure Boards のリンクと接続

Symptoms

  • AB# 参照がリンクされていません。ADO 更新プログラムなし

診断と修正

# Check autolinks
gh api "/repos/$GITHUB_ORG/$REPO/autolinks" | jq -r '.[] | "\(.key_prefix) -> \(.url_template)"'

# Configure autolink (fallback)
gh api -X POST "/repos/$GITHUB_ORG/$REPO/autolinks" \
-f key_prefix="AB#" \
-f url_template="https://dev.azure.com/$ADO_ORG/$ADO_TEAM_PROJECT/_workitems/edit/<num>" \
-f is_alphanumeric=false

# For full integration, ensure webhook exists
gh api "/repos/$GITHUB_ORG/$REPO/hooks" | jq -r '.[] | select(.config.url|contains("dev.azure.com"))'
gh api -X POST "/repos/$GITHUB_ORG/$REPO/hooks/$HOOK_ID/tests"

見つからない場合は、次のコマンドを実行します。

gh ado2gh integrate-boards \
--ado-org "$ADO_ORG" \
--ado-team-project "$ADO_TEAM_PROJECT" \
--github-org "$GITHUB_ORG" \
--github-repo "$REPO" \
--verbose

Azure Pipelines のハイブリッド統合

Symptoms

  • パイプラインはトリガーされません。GitHub リポジトリに接続できない

チェック

# List GitHub-type service connections in ADO
curl -s -u :$ADO_PAT \
"https://dev.azure.com/$ADO_ORG/$ADO_TEAM_PROJECT/_apis/serviceendpoint/endpoints?api-version=6.0-preview.4" | \
jq -r '.value[] | select(.type=="github") | {id,name}'

修正

# Share service connection across projects
gh ado2gh share-service-connection \
--ado-org "$ADO_ORG" \
--ado-team-project "$TARGET_TEAM_PROJECT" \
--service-connection-id "$SERVICE_CONNECTION_ID" \
--verbose

# Rewire pipeline to GitHub repo
gh ado2gh rewire-pipeline \
--ado-org "$ADO_ORG" \
--ado-team-project "$ADO_TEAM_PROJECT" \
--ado-pipeline "$PIPELINE_NAME_OR_PATH" \
--github-org "$GITHUB_ORG" \
--github-repo "$GITHUB_REPO" \
--service-connection-id "$SERVICE_CONNECTION_ID" \
--verbose

緊急ロールバック

使用するタイミング:

  • 移行されたリポジトリの重大な欠陥
  • 大規模なアクセスまたはコンプライアンスエラー

Steps:

  1. 移行を一時停止する。関係者に通知する
  2. ターゲットリポジトリをロールバックします（必要に応じて、承認がある場合）。 
    gh repo delete "$GITHUB_ORG/$REPO" --confirm
  3. ADO の解除; アクセスを復元する
  4. 根本原因を把握する。計画を調整する。移行のスケジュールを変更する