9 min read
Google App Engine Deploy from GitHub: Step-by-Step
Key takeaways
- Connect your GitHub repo to a Cloud Build trigger so every push to main builds and deploys to App Engine automatically.
- Create the App Engine app and pick its region before anything else, because the region is locked once the app exists.
- The Cloud Build service account needs roles like appengine.deployer, storage.objectAdmin, and iam.serviceAccountUser or deploys fail with 403 errors.
- Always run gcloud app deploy manually first; if it fails by hand, the automated trigger will fail the same way with worse error messages.
- App Engine requires a billing card GCP accepts, so if mobile money is your only payment method, a push-to-deploy PaaS removes that blocker.
You can set up a google app engine deploy from GitHub pipeline in about 30 minutes using a Cloud Build trigger: write app.yaml, grant the Cloud Build service account four IAM roles, add a cloudbuild.yaml, then connect the trigger. Each push to your repo then builds and deploys automatically. This guide orders the steps so nothing blocks the next one, and covers the exact permission errors that stop most first attempts.
Can you deploy Google App Engine from GitHub automatically?
Yes. You connect your GitHub repo to Cloud Build, and a push to your branch runs a build that deploys to App Engine. There is no native GitHub App for this the way some PaaS tools offer one-click Git integration; instead you wire up a Cloud Build GitHub trigger that fires on every push.
Three moving parts do the work: an app.yaml describing your service, a Cloud Build service account with the IAM roles to deploy, and a cloudbuild.yaml (or just a build step) that runs gcloud app deploy. Once the trigger is set, git push is your deploy, the same push-to-deploy habit Heroku users miss. If you want that workflow without the Google setup, git push deployment on its own is documented at https://omeganodes.com/blog/deploy-nodejs-with-git-push.
What do you need before you start?
Five things: a GCP project with billing enabled, a GitHub repo, the gcloud CLI installed locally, an App Engine app created, and a region picked up front. That last one matters more than it sounds. Once you create the App Engine app, the region is locked. There is no command to move it later; you would have to create a new project.
Create the App Engine app
Run gcloud app create --region=europe-west (or any supported region). Choose the one closest to your users, because app.yaml never specifies a region. If you would rather skip the GCP setup entirely, a PaaS like Omeganodes handles this layer for you with git push to deploy.
Enable the required APIs
Cloud Build needs two APIs on before anything works: cloudbuild.googleapis.com and appengine.googleapis.com. Enable both with gcloud services enable cloudbuild.googleapis.com appengine.googleapis.com. Missing APIs are the most common cause of a failed first build, so do this now rather than troubleshooting later.
How do you write app.yaml for a first deploy?
Minimal app.yaml example
For a Node.js app, the smallest working file is two lines:
runtime: nodejs20
instance_class: F1
For Python, swap the runtime line for runtime: python312. Both runtimes are "standard environment": Google manages the server, you supply code. The App Engine app.yaml reference lists every supported field, but you can add handlers, env_variables, and scaling rules later. Custom environments (a Dockerfile instead of a managed runtime) are overkill for a side project.
Commit app.yaml to the repo root before touching anything else. It is the file every later step depends on.
Run the first deploy manually
From your project folder, run:
gcloud app deploy
This proves the app runs on App Engine before you automate anything. If it fails here, a Cloud Build trigger will fail the same way, just with worse error messages. Fix it now: check the runtime version matches your local Node or Python version, and confirm gcloud app browse serves your app.
If you would rather skip Google's IAM and billing setup entirely, Omeganodes does git push-to-deploy with automatic HTTPS, and pays with MTN or Airtel Money (https://omeganodes.com/it). The manual-first approach still applies: deploy once by hand, automate second.
Which IAM roles does the Cloud Build service account need?
Cloud Build deploys as a service account, and by default that account cannot touch App Engine. You grant it five roles, each tied to a specific step of the google app engine deploy from github pipeline.
Find the service account
Open the Cloud Build settings page in the Cloud Console (Cloud Build → Settings) or find the account by email: it uses the pattern {project-number}@cloudbuild.gserviceaccount.com. Everything below applies to that one account.
Grant the roles
Run these in Cloud Shell, replacing PROJECT_ID:
for ROLE in cloudbuild.serviceAgent cloudbuild.builds.builder storage.objectAdmin appengine.deployer appengine.serviceAgent iam.serviceAccountUser; do
gcloud projects add-iam-policy-binding PROJECT_ID \
--member="serviceAccount:{project-number}@cloudbuild.gserviceaccount.com" \
--role="roles/$ROLE"
done
Common permission errors and fixes
| Missing role | Error you see | Fix |
|---|---|---|
| Cloud Build Service Agent | Cloud Build Service Agent is missing on trigger run | roles/cloudbuild.serviceAgent |
| Storage Object Admin | AccessDeniedException: 403 writing the staging bucket | roles/storage.objectAdmin |
| App Engine Deployer | The caller does not have permission on app deploy | roles/appengine.deployer |
| App Engine Service Agent | Deploy fails creating the App Engine default service account | roles/appengine.serviceAgent |
| Service Account User | Permission denied on service account during deploy | roles/iam.serviceAccountUser on the runtime service account |
If you would rather skip IAM entirely, push-to-deploy platforms handle this for you; our Omeganodes introduction covers that path.
What does a working cloudbuild.yaml look like?
Full cloudbuild.yaml
This file lives at your repo root, next to app.yaml, and Cloud Build runs it on every push your trigger watches.
steps:
- name: 'node:20'
entrypoint: bash
args:
- -c
- |
npm install
npm test
- name: 'gcr.io/google.com/cloudsdktool/cloud-sdk'
entrypoint: bash
args:
- -c
- |
gcloud auth activate-service-account --key-file=$_KEY_FILE
gcloud app deploy app.yaml --quiet
substitutions:
_KEY_FILE: key.json
timeout: '900s'
The first step installs dependencies and runs your tests; if a test fails, the build stops before anything deploys. The second step authenticates and deploys. If you use impersonation instead of a key file, replace the activate-service-account line with gcloud auth login --no-launch is not needed on Cloud Build; the build's service account already holds the credentials, provided it has the roles covered in the previous section. The Cloud Build service account needs the Cloud Build Service Account role plus App Engine Admin, Storage Admin, and Service Usage roles to deploy to App Engine, per Google Cloud's Cloud Build documentation.
Why --quiet and $PROJECT_ID matter
The --quiet flag skips the "continue? (y/N)" prompt that hangs an unattended build forever. Without it, your build times out waiting for input that never comes. You rarely need to pass $PROJECT_ID explicitly because Cloud Build sets it in the environment, but if your app.yaml or config references the project by name, use $PROJECT_ID as a substitution rather than hardcoding, so the same file works across staging and production projects. One honest caveat: this setup works, but it is real YAML with real IAM to babysit. If you would rather connect a repo and get push-to-deploy with automatic HTTPS and no Kubernetes or YAML at all, Omeganodes does that, with regional pricing and MTN or Airtel Money payment listed on our pricing page.
How do you connect the GitHub repo with a Cloud Build trigger?
Connect GitHub to Cloud Build
Open the Cloud Build console, go to Triggers, and click Connect repository. Choose GitHub (either the GitHub App or Cloud Source Repositories), authorize access, and pick the repo you want to deploy. Grant the requested permissions so Cloud Build can read your commits and set webhooks.
Create the push trigger
Click Create trigger, name it something like deploy-main, and set the event to Push to a branch. Select your repo, set the branch to ^main$, and under Configuration choose Cloud Build configuration file, with the location set to cloudbuild.yaml. Leave the substitutions at their defaults for a first run.
Test the pipeline
Commit a small change, push to main, and open Cloud Build > History in the console. You should see a build start within seconds; click it to watch each step from your cloudbuild.yaml run. When it finishes with a green check, your app is live. If the build fails, the log output tells you which step broke, which is exactly what the next section covers.
Why is your Cloud Build trigger failing?
Where to find build logs
Open the Cloud Build history page in the console and click the failed build to see step-by-step output. From the CLI, gcloud builds log BUILD_ID prints the same thing. The error is almost always in the last few lines of the failing step.
Trigger fires but build fails
Check five things in order. First, the trigger's location must match the region in your cloudbuild.yaml and the App Engine app's region, or the deploy step fails. Second, the build's service account needs the App Engine Admin and Cloud Build Service Account roles from section 4. Third, confirm the Cloud Build and App Engine APIs are enabled on the project. Fourth, quota exhaustion on App Engine instances shows up as a deploy error, not a build error. Fifth, a wrong --app-dir or gcloud app deploy flag silently deploys nothing; the Cloud Build configuration schema lists every valid field so a typo in cloudbuild.yaml is easy to spot.
Trigger does not fire at all
Check the branch pattern first: a trigger set to ^main$ will not run on master. Then verify the Cloud Build GitHub App is installed on the repo and that pushes go to the connected account, not a fork.
What does this cost, and is there a simpler option?
What App Engine costs in practice
App Engine pricing depends on your instance hours, egress, and storage, so a small side project can run cheaply. The catch is not the bill. It is the billing account: GCP requires a card it accepts, and most cards issued in Kenya or Uganda that work locally get declined by international billing checks. If you cannot pass that step, the rest of this guide stays theoretical.
When a git-push PaaS is the better fit
If the billing account is the blocker, a push-to-deploy PaaS that takes mobile money removes it. Omeganodes, our own platform, deploys from GitHub to EU servers with automatic HTTPS, regional pricing, and MTN Mobile Money and Airtel Money payments. No Kubernetes, no YAML. Render, Railway, Fly.io, Ziploy, and Talksasa Cloud are alternatives worth checking.
Honest limits: Omeganodes has no App Engine features like traffic splitting, custom runtimes, or managed Memcache. If you need those, work through the billing problem or pick a competitor.
FAQ
How do I deploy to Google App Engine from GitHub for free?
You cannot deploy entirely for free. App Engine requires a GCP project with a billing account attached, even if your instance hours stay within the free tier. The pipeline itself (Cloud Build triggers, app.yaml, IAM roles) costs nothing to set up, but expect a card on file before the first build runs.
Why does my Cloud Build say 'App Engine Admin API has not been used in project'?
That error means the App Engine API is not enabled. Run gcloud services enable appengine.googleapis.com on the project, and enable cloudbuild.googleapis.com too if you have not already. Missing APIs are the most common cause of a failed first build, and the fix takes seconds once you know which service is silent.
Can I pay for Google Cloud with MTN Mobile Money or Airtel Money?
No. GCP billing requires a card it accepts, and most cards issued in Kenya or Uganda that work locally get declined by international billing checks. If mobile money is your only payment method, a push-to-deploy PaaS that accepts MTN or Airtel Money removes that blocker entirely.
Do I need Kubernetes or YAML files to deploy from GitHub to a PaaS?
No. The App Engine route needs app.yaml and cloudbuild.yaml, but push-to-deploy platforms skip both: you connect a repo, and each push builds and deploys with automatic HTTPS handled for you. You give up fine-grained control like traffic splitting and custom runtimes, which most side projects never touch anyway.
How do I roll back a bad App Engine deploy made by a trigger?
Use version traffic splitting: every trigger deploy creates a new version, so previous versions keep running. In the console, migrate traffic back to the last known-good version, or run gcloud app versions to list them and point traffic at the earlier one. Fix the bug, push, and the trigger deploys forward again.
Deploy at the speed of Africa
World-class hosting, open to every developer, wherever you build and however you pay. Start free in a couple of minutes — no credit card, no lock-in.