GitHubActionsでECRにDockerImageをPushすると403になる原因と対処法

個人開発のアプリで、GitHubActionsからAmazonECRへDockerイメージをpushするワークフローを動かしていました。2026年2月11日には通っていたpushが、許可する操作を変えないまま2月19日に403 Forbiddenで失敗するようになりました。IAMロールの権限にecr:BatchGetImageを足し、7分後にもう一度pushすると通りました。この記事では、なぜその権限が要るのか、なぜ急に要るようになったのかを、公式の情報で確かめた内容とあわせてまとめます。
忙しい人向け
GitHubActionsのIAMロールにecr:BatchGetImageが無いと、pushの途中で行うマニフェストの存在確認(HEADリクエスト)がECRに拒否され、403になります。ecr:BatchGetImageはAWS公式が示すpush用ポリシーにも含まれている権限なので、これを足せば直ります。急に起きたのは、2026年2月にGitHubのUbuntuのrunnerのDockerが29に上がり、pushの動きが変わった時期と重なっていたためと考えられます。
問題発生時のファイル構成(例)
my-app/
├─ .github/
│ └─ workflows/
│ └─ app-deploy.yml # ビルドしてECRにpushするワークフロー
├─ app/
│ └─ docker/
│ └─ Dockerfile
└─ terraform/
└─ modules/
└─ iam/
└─ main.tf # GitHubActions用のIAMロールとポリシー
IAMロールとポリシーはTerraformで管理していて、ワークフローはOIDCでそのロールを引き受けてからpushします。
発生環境
- 発生日: 2026年2月19日(日本時間)
- runner: GitHubホステッドランナー
ubuntu-latest - Action:
actions/checkout@v4aws-actions/configure-aws-credentials@v4(OIDCでIAMロールを引き受ける)aws-actions/amazon-ecr-login@v1
- ビルドとpush:
docker/build-push-actionは使わず、runでdocker buildとdocker pushを直接実行 - IAM: Terraformで管理(
aws_iam_role_policy) - リージョン: ap-northeast-1
当時のrunnerイメージのバージョンとDockerのバージョンは、ログの保存期間が過ぎていて確認できませんでした。
ワークフローは次のとおりです(シークレットの名前は伏せています)。
jobs:
build-and-push-ecr:
runs-on: ubuntu-latest
permissions:
id-token: write
contents: read
steps:
- uses: actions/checkout@v4
- uses: aws-actions/configure-aws-credentials@v4
with:
role-to-assume: ${{ secrets.AWS_GITHUB_ACTION_ROLE_ARN }}
aws-region: ${{ secrets.AWS_REGION }}
- uses: aws-actions/amazon-ecr-login@v1
id: login-ecr
- name: Dockerイメージのビルド&プッシュ
env:
ECR_REGISTRY: ${{ steps.login-ecr.outputs.registry }}
ECR_REPOSITORY: ${{ secrets.ECR_REPOSITORY }}
run: |
docker build -f app/docker/Dockerfile -t $ECR_REGISTRY/$ECR_REPOSITORY:latest .
docker push $ECR_REGISTRY/$ECR_REPOSITORY:latest
症状
docker pushのステップで、次のエラーが出て失敗しました。
unknown: unexpected status from HEAD request to https://XXXXXXXXXXXX.dkr.ecr.***.amazonaws.com/v2/***/manifests/sha256:YYYYYYYYYY:
403 Forbidden
- ECRへのログイン(
amazon-ecr-login)までは成功している - 失敗するのは
docker pushのステップだけ - 2月11日には、IAMポリシーで許可する操作が同じままpushが通っていた
GitHubActionsの実行履歴は次のようになっていました(時刻は日本時間)。
| 日時 | 結果 | IAMポリシーのecr:BatchGetImage |
|---|---|---|
| 2026-02-11の23:41 | 成功 | 無し |
| 2026-02-19の00:00 | 失敗(403) | 無し |
| 2026-02-19の00:07 | 成功 | 追加した |
00:00と00:07の間に変えたのはIAMポリシーだけです。どちらの実行も、ワークフローを動かすためにアプリのコードを1行変えただけのpushでした。
前提条件
- GitHubActionsからOIDCでIAMロールを引き受けて、ECRのプライベートリポジトリにpushしている
- IAMロールの権限を、push用の操作だけに絞っている(
AmazonEC2ContainerRegistryPowerUserなどのマネージドポリシーを使っていない) - エラーが
HEAD requestと/manifests/を含む403 Forbiddenである
ローカルのPCからのpushは通るのにGitHubActionsだけ失敗する場合も、同じ原因の可能性があります。
原因
マニフェストの存在確認にecr:BatchGetImageが要る
エラーの中身を見ると、pushの途中で/v2/<リポジトリ>/manifests/<ダイジェスト>にHEADリクエストを送り、それが403になっています。コンテナレジストリの仕様(OCIDistributionSpec)では、このHEADリクエストは「そのマニフェストがリポジトリにすでにあるか」を確かめるためのもので、あれば200、無ければ404が返ります。
ECRでは、マニフェストを読み取る操作の権限はecr:BatchGetImageです。AWSのAPIリファレンスにも、イメージのpull時にマニフェストを取得するためにこのAPIが呼ばれると書かれています。今回のロールにはpushの書き込み系の権限しか無かったので、存在確認のHEADリクエストが「読み取りの権限が無い」として403で拒否されていました。
AWS公式のドキュメントが示すpush用のIAMポリシーにも、ecr:BatchGetImageは最初から含まれています。今回のポリシーは、そこからこの権限が抜けていたことになります。
急に起きたのはrunnerのDockerの更新と重なっていたため
2月11日には許可する操作が同じままpushが通っていたので、変わったのはGitHubActions側だと考えられます。GitHubは、Ubuntuのrunnerイメージに入っているDockerを28から29.1.5へ上げると告知していて、2026年2月11日ごろから配布が始まりました。Docker29では、新規インストールで「containerdイメージストア」が既定のストレージになり、pushの動きが変わります。告知のissueには、更新のあとにECRへのpushが403になり、ecr:BatchGetImageを足したら直ったという報告が複数寄せられていました。
このDocker29への更新は影響が大きかったため、2026年2月19日(UTC)に、1つ前のDocker28のイメージへ戻すことが告知され、順次戻されました。今回の失敗は、ちょうどDocker29が配られていた期間に起きていました。ただし、当時の実行ログが残っていないため、失敗した実行がDocker29で動いていたことまでは確かめられていません。
2026年5月の時点で、Ubuntu24.04のイメージはあらためてDocker29に上げる予定で、Ubuntu26.04のイメージは最初からDocker29になると告知されています。runnerを変えたときにまた同じエラーが出ないよう、権限は公式のポリシーに合わせておくのが安全です。
OIDCの信頼ポリシーとの関係
OIDCで使うIAMロールには、「誰がこのロールを引き受けられるか」を決める信頼ポリシーと、「ロールで何ができるか」を決める権限ポリシーの2つがあります。今回の403は権限ポリシーの不足によるもので、信頼ポリシーは関係ありません。
信頼ポリシーの条件(token.actions.githubusercontent.com:subなど)が合っていない場合は、configure-aws-credentialsのステップでロールを引き受けられずに止まります。今回はロールの引き受けとECRへのログインが成功し、docker pushの途中で失敗していたので、信頼ポリシーではなく権限ポリシーを疑うべき状況でした。
対処手順
手順1: IAMロールの権限ポリシーにecr:BatchGetImageを追加する
Terraformの差分は次のとおりです(名前は伏せています)。
resource "aws_iam_role_policy" "github_action_ecr_push" {
name = "GithubActionEcrPushPolicy"
role = aws_iam_role.github_action.id
policy = jsonencode({
Version = "2012-10-17",
Statement = [
{
Action = "ecr:GetAuthorizationToken",
Effect = "Allow",
Resource = "*"
},
{
Action = [
"ecr:UploadLayerPart",
"ecr:PutImage",
"ecr:InitiateLayerUpload",
"ecr:CompleteLayerUpload",
"ecr:BatchCheckLayerAvailability",
"ecr:BatchGetImage" # 今回追加した権限
],
Effect = "Allow",
Resource = var.ecr_repository_arn
}
]
})
}
ecr:GetAuthorizationTokenは特定のリポジトリに絞れないため、Resourceを*にして別のステートメントに分けています。それ以外の権限は、pushするリポジトリのARNに絞っています。この構成はAWS公式のpush用ポリシーの例と同じです。
手順2: 変更を反映する
terraform plan
terraform apply
planで、変わるのがaws_iam_role_policyのpolicyだけであることを確かめてからapplyします。
手順3: ワークフローを再実行して確かめる
GitHubのActionsタブから失敗したワークフローを再実行するか、もう一度pushします。今回はもう一度pushしたところ、docker pushのステップが成功し、ワークフロー全体が成功になりました。
ECRにイメージが入ったかは、AWSCLIでも確かめられます。
aws ecr describe-images \
--repository-name <リポジトリ名> \
--image-ids imageTag=latest \
--region ap-northeast-1
imagePushedAtが再実行した時刻になっていれば、pushできています。
まとめ
HEAD requestと/manifests/を含む403は、マニフェストの存在確認に要るecr:BatchGetImageが無いことが原因でした- 書き込み系の権限だけでpushできていたのは、runnerのDockerが28だった間だけでした。公式のpush用ポリシーには最初から
ecr:BatchGetImageが入っているので、それに合わせておくと安全です - OIDCの信頼ポリシーの問題なら、ロールの引き受けの時点で失敗します。どのステップで止まったかを見ると、どちらのポリシーを見直すべきか判断できます
Terraformを手元で動かす環境はDockerでTerraformの実行環境を構築する方法に、GitHubActionsでのデプロイの別の例はGitHubActionsとClaspでGASを自動デプロイする方法にまとめています。
前まで動いてたの唐突に動かなくなるのやめてほしい。。。
あと俺の30分返して!
参考リンク
- IAM permissions for pushing an image to an Amazon ECR private repository - Amazon ECR
- BatchGetImage - Amazon ECR API Reference
- OCI Distribution Specification(Checking if content exists in the registry)
- Docker Server and Client will be updated to version 29.1.* - actions/runner-images #13474
- containerd image store with Docker Engine - Docker Docs
- Configuring OpenID Connect in Amazon Web Services - GitHub Docs
- GitHubActionsでECRにpushしようとしたら権限エラーでハマった - Qiita



