Heroku GitHub integration promises push-to-deploy. Connect your repo, enable auto-deploy, and every push goes live automatically. That’s the pitch.
What you actually get: an OAuth connection that can be revoked without warning, a shared build queue that can delay your deploy by 15 minutes, and a pipeline that goes green while your database is completely out of sync. The heroku github integration works under ideal conditions. When those conditions break, your pipeline breaks with them.
This post covers how it works, where it genuinely falls short, and what teams are using instead.
How Heroku GitHub Integration Works
Setting up the integration is straightforward. In your Heroku Dashboard, open your app, go to the Deploy tab, and select GitHub as the deployment method. You authenticate once with your GitHub account, search for your repo by name, and click Connect.
From there, you have two modes:
Manual deploys: you select a branch and click Deploy Branch. Full control over when code goes to production, nothing happens automatically.
Automatic deploys: you pick a branch, enable auto-deploy, and every push to that branch triggers a Heroku build. There’s an optional “Wait for CI to pass before deploy” checkbox. If you have Travis CI, GitHub Actions, or another CI tool creating commit statuses, Heroku will wait for all checks to pass before building.
There’s also Review Apps: when enabled on a Heroku Pipeline, every open pull request gets its own temporary Heroku app spun up automatically. Useful for QA and design review without touching production.
On paper, that covers most of what a CI/CD pipeline needs. In practice, the gaps show up fast.
**_
Want to understand the full picture of how Heroku handles deployments before diving into the limitations? The complete guide to Heroku app deployment covers the architecture, dyno types, and what actually happens between a git push and a running app.
_**
The Real Limitations of Heroku GitHub Integration
No Auto-Migrations: Deploys Can Break Your Database
This is the one that catches teams off guard. When Heroku deploys via GitHub, it builds your app and restarts your dynos. It does not run database migrations.
For Django, Rails, or Laravel apps, that means every deployment that includes a schema change needs a separate manual step:
heroku run rake db:migrate
heroku run python manage.py migrate
heroku run php artisan migrate
Or you configure Heroku’s Release Phase to run migrations automatically. That is a separate feature, documented separately, that you have to wire up yourself. Many teams skip this during initial setup. The first time they deploy a migration without it, the app starts returning 500 errors because the schema is ahead of what the running code expects.
It’s a solvable problem, but “connect GitHub and it deploys” isn’t the full picture when your stack uses a relational database.
GitHub Actions with Heroku Is a DIY Job
If you want to use GitHub Actions to deploy to Heroku, adding test steps, lint checks, or custom build scripts before the deploy, there is no official Heroku action. What you find on the GitHub Marketplace is a community-maintained action: akhileshns/heroku-deploy.
Getting it working requires:
- Storing your Heroku API key as a GitHub Secret (HEROKU_API_KEY)
- Manually installing the Heroku CLI in your workflow YAML, because ubuntu-latest no longer ships it
- Pinning the action version, because the community action has changed behavior between versions and an unpinned update can silently break your pipeline
A minimal working workflow looks like this:
name: Deploy to Heroku
on:
push:
branches: [main]
jobs:
deploy:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
- name: Install Heroku CLI
run: curl https://cli-assets.heroku.com/install.sh | sh
- uses: akhileshns/heroku-deploy@v3.15.15
with:
heroku_api_key: ${{ secrets.HEROKU_API_KEY }}
heroku_app_name: "your-app-name"
heroku_email: "your@email.com"
Your Heroku API key lives as a plain text secret in GitHub. The CLI install step fetches a remote shell script on every run. The action itself is maintained by an individual contributor, not Heroku. Any one of these moving parts can break without Heroku having any involvement, or any obligation to fix it.
_**
Most teams using GitHub Actions for deploys are trying to solve the same problem: removing manual steps from their release process. The guide to eliminating manual steps in your CI/CD workflow covers the patterns that actually work across platforms.
**_
IP Allowlists Block the Integration for Enterprise Orgs
GitHub organisations can restrict which OAuth apps and IP ranges are allowed to access org repositories. Heroku’s outbound IP addresses cannot be whitelisted at the GitHub org level. This is a documented limitation with no native fix.
For teams in regulated industries or enterprises with strict security policies, this means the native Heroku GitHub integration is completely unavailable.
Heroku’s official workaround is to run a self-hosted GitHub Actions runner as a Heroku app, then use that runner to deploy to Heroku via the Platform API. It works, but it requires Docker images, a 30-day mandatory runner update cycle, and custom YAML. A significant infrastructure setup for what should be a one-click connection.
The 2022 OAuth Security Breach
In April 2022, Heroku announced it was disabling GitHub OAuth integration entirely. Attackers had used stolen OAuth tokens to download code from private repositories. The integration stayed offline for several weeks. No fixed timeline was given and no automatic fallback was provided.
Teams with auto-deploy configured suddenly had no pipeline. The only option was manual git push heroku main from a local machine. For teams without CLI access set up, or running fully automated release processes, it caused real outages.
The integration was eventually restored. But the incident made one thing clear: the Heroku-GitHub OAuth link is a single dependency that can be severed at any time for reasons entirely outside your control.
Git Submodules Are Not Supported
If your repository uses Git submodules, Heroku GitHub integration will not deploy correctly. When GitHub generates the source tarball it sends to Heroku, submodule contents are not included. Heroku receives an incomplete codebase and the build either fails or produces a broken app.
There’s no workaround within the integration itself. The options are: restructure your repo to remove submodules, or stop using GitHub integration and push via Heroku’s Git remote directly.
Build Queue Delays on Shared Infrastructure
When you push to GitHub and auto-deploy triggers, your build enters a shared queue. On Heroku’s shared infrastructure, this means your push can sit waiting for 5 to 15 minutes before the build starts during peak usage periods.
For solo projects, this is barely noticeable. For teams shipping multiple times a day, or trying to push a hotfix to production, the unpredictability adds up.
**_
Heroku’s infrastructure pricing plays a direct role here. Higher-tier dynos get priority build resources. The full breakdown of Heroku pricing and dyno tiers shows what you’re actually paying for at each level and where the trade-offs sit.
_**
Heroku GitHub Deploy vs GitHub Actions: Which Should You Use?
Teams setting up Heroku CI/CD usually end up choosing between the two approaches. Neither is clearly better. They each trade off different problems.
Native GitHub integration (Dashboard Deploy tab):
- Simpler setup, no YAML required
- Works immediately after OAuth authentication
- Limited to push-to-deploy. No pre-deploy tests, no custom build steps
- Shares the build queue with every other Heroku app
- No control over migration timing or release gates
GitHub Actions via akhileshns/heroku-deploy:
- Full control over pipeline. Add tests, linting, and build steps before deploy
- Runs in GitHub’s infrastructure, not Heroku’s build queue
- Requires API key in GitHub Secrets
- Requires manual Heroku CLI installation in YAML
- Dependent on a community-maintained action with no official SLA
In both cases, you’re one step removed from a complete automated pipeline. Native integration skips customisation. Actions add complexity and a third-party dependency.
**_
For teams that want to fully automate their deployment pipeline without patching together tools, the best AI solutions for automating code deployments and CI/CD breaks down what modern platforms do natively vs what still requires manual wiring.
_**
**_
If you’ve been searching for a simpler path to GitHub-connected deploys, how to auto-deploy your apps from GitHub in one click shows what that flow looks like without the limitations above
_**.
What Is Kuberns and How Is It Different?
Kuberns is an Agentic AI cloud deployment platform built on AWS. You connect your GitHub repo once. From there, Kuberns’ AI agent reads your codebase, identifies your stack, configures the entire deployment environment, and ships your app. No configuration files required from you.
This is what that means in practice:
Agentic AI deployment: Kuberns does not ask you to select a buildpack or write a Procfile. Its AI reads your package.json, requirements.txt, composer.json, or Dockerfile and figures out how to build and run your app automatically. Node.js, Python, Django, Rails, PHP, Go, containers. It handles all of them.
One-click GitHub integration: Connect your repo from the Kuberns dashboard. No OAuth scope negotiation, no API key in GitHub Secrets, no service hook registration. Every push to your configured branch triggers a full deploy automatically.
No YAML, no manual steps: There is no workflow file to maintain, no CLI to install, no community action to pin. The AI handles the build configuration, dependency installation, environment setup, and HTTPS provisioning end to end.
No per-user pricing: Kuberns pricing is based on your infrastructure usage, not your team size. Add developers to your project without the cost scaling linearly with headcount.
Dedicated infrastructure, no build queue: Deployments run on dedicated AWS infrastructure. There is no shared queue. Your push does not wait behind other teams’ builds.
Auto-scaling without dyno management: Kuberns scales your app based on real traffic. No dyno configuration, no manual scaling commands, no choosing between Eco and Standard and Performance tier. The platform handles it.
Up to 40% lower cost vs Heroku: On equivalent workloads, Kuberns infrastructure costs run up to 40% less than comparable Heroku dyno and add-on configurations.
**_
Trying to make sense of the PaaS landscape before committing? The best PaaS providers in 2026 compared covers the full spectrum from traditional platforms to AI-native options, with real pricing and trade-offs for each.
_**
Here is how Kuberns goes beyond Heroku GitHub Integration:
- Agentic AI deployment: the AI configures your entire build and release pipeline, not just triggers a push
- One-click GitHub connection with no secrets, no hooks, no OAuth dependencies that can be revoked
- Auto-scaling that responds to real traffic without manual dyno configuration
- Unified monitoring and logging with real-time metrics and proactive alerts
- No per-user pricing as your team grows
- Save up to 40% on cloud infrastructure costs using Kuberns
- No servers to maintain and no DevOps hiring required
Conclusion: Your Deploy Pipeline Shouldn’t Need This Much Work
Heroku GitHub integration works when everything lines up: no IP policies, no submodule dependencies, no need for pre-deploy tests, and no bad timing with an OAuth outage. Add a team, a database migration, a security policy, or a GitHub Actions workflow and you are immediately in DIY territory. Writing YAML, managing secrets, debugging a community-maintained action.
That is not a CI/CD pipeline. That is a pipeline you also have to maintain.
Kuberns was built to replace that fragile chain entirely. Connect your repo once. Push code. The AI handles the rest: build, deploy, scale, monitor. No configuration files, no manual migration steps, no third-party dependencies between your push and your production app.
Top comments (0)