gcloud "app deploy" Fails - App Engine Build & Deploy in CI

gcloud app deploy builds your service through Cloud Build and ships it to App Engine, and one of those steps failed - a build error, an invalid app.yaml, or no App Engine application in the project yet.

What this error means

gcloud app deploy fails during the Cloud Build phase or while creating the version. A build/config error reproduces every run; a missing App Engine app needs a one-time gcloud app create. The build log link in the output has the detail.

gcloud output

ERROR: (gcloud.app.deploy) Cloud build failed. Check logs at
https://console.cloud.google.com/cloud-build/builds/...
# or
ERROR: (gcloud.app.deploy) The current Google Cloud project does not have an
App Engine application. Use 'gcloud app create' to initialize one.

Common causes

Cloud Build or app.yaml error

The buildpack/Dockerfile build failed, or app.yaml declares an unsupported runtime/entrypoint, so the version is never created.

No App Engine application in the project

App Engine requires a one-time gcloud app create (which also fixes the region). Without it, deploys fail until the application exists.

How to fix it

Read the Cloud Build log and fix the build

Open the build log URL in the error to find the underlying compile/install failure.
Confirm app.yaml uses a supported runtime and a correct entrypoint.
Reproduce the buildpack build locally where possible to iterate faster.

Initialize App Engine once

Create the App Engine application (and its region) before deploying.

Terminal

gcloud app create --region=us-central --project my-proj
gcloud app deploy app.yaml --project my-proj --quiet

How to prevent it

Initialize App Engine (gcloud app create) as a one-time project setup step.
Validate app.yaml runtime/entrypoint before deploying.
Enable required APIs (App Engine Admin, Cloud Build) up front.