やりかた

公式ドキュメントに書いてある通りですが。

1. BuildProjectのサービスロールに権限を追加

{
  "Effect": "Allow",
  "Action": [
    "ssmmessages:CreateControlChannel",
    "ssmmessages:CreateDataChannel",
    "ssmmessages:OpenControlChannel",
    "ssmmessages:OpenDataChannel"
  ],
  "Resource": "*"
}

2. ビルド一時停止するコマンド(codebuild-breakpoint)をbuildspecに追加しておく

phases:
  build:
    commands:
      - codebuild-breakpoint ←追加
      - python -m unittest discover tests

3. 「Enable session connection」にチェックを入れて実行

[Advanced build overrides (高度なビルドの上書き)] で環境上書き設定を表示させる
[Enable session connection(セッション接続を有効にする)] にチェックを入れる

(オプション)ソースの変更

例えば普段はCodePipelineをソースにしているプロジェクトで、そのままマネコンから実行しようとするとエラーが出ます。
CodePipelineで直前に失敗したビルドのアーティファクトをS3ソースとして直接指定してやることで同じソースから実行できます。

直前に失敗したビルドの Srouce Vesionからバケットとアーティファクトファイルを確認
それを手動実行のビルドのソースとして指定

4. codebuild-breakpointのところで止まるのでブラウザから入る

接続可能な状態になると Buils statusの右下に Session Manager へのリンクが出現するのでクリック

codebuild-breakpointで止めなくても現れますが、入ろうとしたらビルドが進んで終わっちゃったりしたので、止めて入るのがいいかなと思います。

5. おわったら「codebuild-resume」でビルドを再開して出る

CodeBuild側からみた実行状況

ローカルで成功していたはずのunittestが失敗していましたが、中に入って調べたおかげで原因解明できました。やったー！

備考

普段CodePipelineからCodeBuildを実行しているんですが、その場合「Enable session connection」にチェックを入れる相当の設定が見つけられなかったので、CodeBuild単独で動かして中に入っています。

普段から「codebuild-breakpoint」をbuildspecに仕込んでおいて、デバッグが必要なときだけCodeBuildから「Enable session connection」有効にして実行する。という運用がいいんですかね。

※「Enable session connection」してない場合はcodebuild-breakpointおよび codebuild-resume コマンドは無視される仕様。