ボタンを押すだけでコード変換が走る ― AWS Transform custom を GitHub Actions で自動化する

概要

アプリケーションサービス本部ディベロップメントサービス4課の池上です。

今回は、最近リリースされた AWS Transform custom を GitHub Actions から呼び出して、config.yaml による指示でコード変換を自動化するCI/CDパイプラインの構築方法を紹介します。config.yaml の書き方についてもあわせて解説します。

AWS Transform custom は、エージェント型AIを活用して大規模なコード・フレームワーク・ライブラリのモダナイゼーションを行うサービスです。自然言語で変換ルールを定義し、複数のコードベースに対して一貫した変換を適用できます。

AWS Transform custom 公式ドキュメント

Transform customをGitHub Actionsで行うための初期設定

手順1　AWS側にOIDCプロバイダーを作成

GitHubとAWSアカウント同士で OIDC接続を行ってください。

まずはIDプロバイダーを作成します。

プロバイダーの詳細で プロバイダーのタイプでOpenID Connectを選び、 プロバイダーのURLをhttps://token.actions.githubusercontent.com 対象者をsts.amazonaws.comに設定します。

手順2　OIDC用IAMロールを作成

手順1終了後OIDC用のIAMロールを作成します。 この時カスタム信頼ポリシーでJSONで作成するようにします。

以下のようなJSONを入力してください。

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "",
      "Effect": "Allow",
      "Principal": {
        "Federated": "arn:aws:iam::<Transform customの変換を行うAWSアカウントを入力>:oidc-provider/token.actions.githubusercontent.com"
      },
      "Action": "sts:AssumeRoleWithWebIdentity",
      "Condition": {
        "StringLike": {
          "token.actions.githubusercontent.com:aud": "sts.amazonaws.com",
          "token.actions.githubusercontent.com:sub": [
            "repo:ここにリポジトリ名を入力",
            "repo:追加する場合はここに記載"
          ]
        }
      }
    }
  ]
}

一旦空のロールを作成します 。

ロール名はわかりやすいものであればなんでも構いません。

手順3　ロールにインラインポリシーをアタッチ

手順2の後、続いて作ったロールにインラインポリシーを作成します。

こちらもJSONでインラインポリシーを作成してください。

以下のようなポリシーであればOKです。

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "transform-custom:ConverseStream",
        "transform-custom:ExecuteTransformation"
      ],
      "Resource": [
        "*"
      ]
    }
  ]
}

こちらでAWS側の準備は完了です。続いて GitHub Actions の main.yml を設定します。詳細は次の「運用の基本方針」セクションを参照してください。

GitHub側での設定のやり方

リポジトリ内部の基本構成

config.yaml に変換指示をすべて記述し、GitHub Actions のCI/CD環境から非対話型で実行します。

リポジトリ
├── config.yaml                  ← 変換指示の本体（必須）
├── document_references/         ← エージェントに読ませる参照ドキュメント（必須ではない）
│   ├── phase2_conversion_scripts.md（ファイル名は自由）
│   ├── phase3_inference_rewrite.md
│   └── ...
├── .github/workflows/main.yml   ← CI/CD 定義
└── (アプリケーションコード)

実行コマンド

このようなコマンドを盛り込んだ、GitHub Actionsの設定ファイルを書くことによって、GitHub Actions経由でAWS Transform customを稼働させることが可能になります。

atx custom def exec -x -t -g file://config.yaml

フラグ	意味
-x	非対話型モード（ユーザー入力なし）
-t	すべてのツール実行を自動承認
-g file://config.yaml	設定ファイルを指定

注意: -t はすべてのセキュリティガードレールをバイパスします。CI/CD 環境では問題ありませんが、ローカル実行時は注意してください。

ここでは、Run workflowというボタンを押すことによってTransform customが稼働して、古いコードに変換がかかるように設定をしたコマンド例を載せます。

name: ATX Transformation and Push

on:
  workflow_dispatch:

jobs:
  atx-execution:
    runs-on: ubuntu-latest
    permissions:
      id-token: write    # OIDC認証に必要
      contents: write    # リポジトリへのpushに必要
    steps:
      # 1. リポジトリのコードを取得
      - name: Checkout code
        uses: actions/checkout@v6
        with:
          fetch-depth: 0 # 全履歴を取得（push時の競合回避のため）

      # 2. AWS 認証設定（us-east-1 を使用）
      - name: Configure AWS credentials
        uses: aws-actions/configure-aws-credentials@v6
        with:
          aws-region: 'us-east-1'
          role-to-assume: '<先ほど作成したOIDCロールを記入>'
          role-duration-seconds: 43200 

      # 3. ATX ツールのインストール
      - name: Install ATX via Script
        run: |
          curl -fsSL https://desktop-release.transform.us-east-1.api.aws/install.sh | bash
          # インストール先をGitHub Actionsの環境パスに追加
          echo "$HOME/.atx/bin" >> $GITHUB_PATH

      # 4. ATX による変換の実行
      - name: Run ATX Transformation
        run: |
          export PATH="$HOME/.atx/bin:$PATH"
          export AWS_REGION=us-east-1
          atx custom def exec -x -t -g file://config.yaml

      # 5. ATX の生成物（指示書やログ）を保存
      - name: Upload ATX Artifacts and Logs
        if: always()
        uses: actions/upload-artifact@v6
        with:
          name: atx-results-and-logs
          path: /home/runner/.aws/atx/custom/
          retention-days: 7


      # 6. 変更されたファイルをリポジトリに Push する
      - name: Push ATX Result Branch to GitHub
        run: |
          # 1. Git のユーザー設定
          git config --global user.name "github-actions[bot]"
          git config --global user.email "github-actions[bot]@users.noreply.github.com"
          
          # 2. atx が作成したステージングブランチの名前を取得
          STAGING_BRANCH=$(git branch --list 'atx-result-staging-*' | sed 's/* //g' | tr -d ' ' | head -n 1)
          
          if [ -n "$STAGING_BRANCH" ]; then
            echo "Found staging branch: $STAGING_BRANCH"
            # 3. そのブランチを GitHub (origin) へ直接プッシュする
            git push origin "$STAGING_BRANCH"
            echo "Successfully pushed $STAGING_BRANCH to GitHub."
          else
            # ブランチが作られず、ファイルが直接書き換わっている場合への備え
            if [ -n "$(git status --porcelain)" ]; then
              echo "No staging branch but files changed. Committing to current branch..."
              git add .
              git commit -m "chore: auto-transformation by ATX"
              git push origin HEAD
            else
              echo "No changes found on any branch."
            fi
          fi

config.yaml の書き方

構造

# 変換対象リポジトリのパス
codeRepositoryPath: .

# 使用する変換定義（AWS マネージド or 自作）
transformationName: AWS/python-version-upgrade

# ビルド・検証コマンド（必ず設定すること）
buildCommand: "コマンド"

# エージェントへの指示
additionalPlanContext: |
  ここに変換の詳細指示を書く

各パラメータの説明

codeRepositoryPath — 変換対象のパス。リポジトリルートなら . を指定。

transformationName — 使用する変換定義の名前。atx custom def list で一覧を確認できる。AWS マネージド変換は AWS/ プレフィックスがつく（例: AWS/python-version-upgrade, AWS/java-version-upgrade）。

buildCommand — 変換の各ステップ後に実行される検証コマンド。省略せずに必ず設定すること。 エージェントの品質に直結する。

additionalPlanContext — エージェントへの追加指示。本来は軽い補足用だが、詳細な変換仕様をここに書いても問題なく動作する。

additionalPlanContext の書き方のコツ

• フェーズを分けて構造的に書く
• ファイル名と変更内容を具体的に指定する
• 「CRITICAL:」「IMPORTANT:」で重要な制約を強調する
• document_references/ 内のファイルを「読め」と明示的に指示する
• 制約条件（変更してはいけないもの）を明記する
• 期待する成果物を列挙する

config.yaml の実例

# 変換対象のルートパス
codeRepositoryPath: .

# 変換タイプ
transformationName: AWS/python-version-upgrade

# ビルド検証コマンド
buildCommand: "pip install -r requirements.txt && python -m compileall ."

# AIエージェントへの追加指示
additionalPlanContext: |
  ## 目的
  Lambda 関数の Python 3.9 → 3.12 へのバージョンアップ

  ## 対応方針
  - requirements.txt の各ライブラリを Python 3.12 対応バージョンに更新する。
  - 非推奨・削除された標準ライブラリの置き換え

---

変換結果の確認方法

ATX は変換実行時に以下のアーティファクトを生成します。GitHub Actions の artifacts からダウンロードして確認してください。

ファイル	内容
plan.json	エージェントが生成した変換計画（ステップ、対象ファイル、検証コマンド）
worklog.log	各ステップの実行結果、変更ファイル、コミット状況
validation_summary.md	全検証基準の合否サマリ
debug.log	ビルド検証結果、最終的な整合性チェック
git_instructions.md	PR 作成手順、コミット一覧

変換結果は atx-result-staging-* ブランチに push されます。PR を作成してレビューしてください。

AWS マネージド変換の一覧

最新の一覧は atx custom def list で確認してください。2026年4月10日時点で利用可能な主要なものは以下の通りです。

変換名	説明
AWS/java-version-upgrade	Java バージョンアップ（任意バージョン間）
AWS/python-version-upgrade	Python バージョンアップ（3.8/3.9 → 3.11/3.12/3.13）
AWS/nodejs-version-upgrade	Node.js バージョンアップ
AWS/java-aws-sdk-v1-to-v2	Java AWS SDK v1 → v2
AWS/nodejs-aws-sdk-v2-to-v3	Node.js AWS SDK v2 → v3
AWS/python-boto2-to-boto3	Python boto2 → boto3
AWS/comprehensive-codebase-analysis	コードベースの静的解析・ドキュメント生成

これらは現状簡単なもの（Lambda関数のPythonコードのバージョンを上げるようなレベル）であればこちらだけでも十分なものの、 AIパッケージの大規模更新などでは、additionalPlanContextへの追記や、document_references/への補足資料の追記が必要になります。

トラブルシューティング

症状	対処法
atx コマンドが見つからない	echo "$HOME/.atx/bin" >> $GITHUB_PATH を確認。Node.js 20以上が必要
認証エラー	IAM ロールの権限と AWS_REGION=us-east-1 の設定を確認、またはGitHub Actionsの設定ファイルの中身を確認
変換結果の品質が低い	buildCommand の設定を確認。additionalPlanContext の指示を具体化する
document_references を読んでくれない	パスを絶対指定するか「IMPORTANT: ～を必ず参照」と強調する

まとめ

大規模なコードのモダナイゼーションといえば、これまでは手作業で地道にファイルを書き換えるイメージが強く、依存関係が複雑なライブラリ設定やコード変更は特に手間のかかる重い作業でした。 しかし、Transform custom の config.yaml にやりたいことを構造的に書き出してみると、エージェントが意図を汲み取ってくれる場面が多くあり、指示の書き方次第で変換の品質が大きく変わるという手応えを得られたのは、今回の大きな収穫です。 今回の構成であれば、一度信頼ポリシーとロールを整えてしまえば、Run workflow を押すだけで変換が走り、ブランチまで自動で作成されます。これによって安全にモダナイズができ、さらにログも自動的に生成してくれるので変換の検証をする際にも便利な構成だと思いました。