# AkhileshNS/heroku-deploy: pushing a Heroku app from a GitHub Actions workflow

> AkhileshNS/heroku-deploy is a small Node based GitHub Action that deploys an app to Heroku by driving the Heroku CLI from a workflow step. It is easy to wire up, but it demands a CLI installed on the runner, a Heroku API key secret, and manual intervention on the Heroku side to avoid conflicting with the platform's own deployment sync.

**AkhileshNS/heroku-deploy** — A simple github action that dynamically deploys an app to heroku

- Repository: https://github.com/AkhileshNS/heroku-deploy
- Stars: 1,009 · Forks: 249
- Language: JavaScript
- License: MIT
- Published: 2026-10-19 · Updated: 2026-10-19 · Language: en
- Canonical page: https://hysenlabs.com/projects/akhileshns-heroku-deploy

## What the action actually does in a workflow step

The mechanism is deliberately blunt. The README describes the action as working by running Heroku commands in a shell through NodeJS, which means there is no bespoke deployment protocol to understand and no API of its own to learn. The action executes the Heroku command line tool on the runner, and the Heroku CLI does the actual work of building, pushing and releasing the app.

The code lives in a single entry file, index.js, with package.json pointing its main field at that file. The runtime dependencies are short: @actions/core for reading inputs and writing outputs in the GitHub Actions convention, phin for HTTP requests, and dotenv, which pairs with the ENV File part of the documentation. There is also a .nvmrc at the root, so the Node version used by the action is pinned in the repository rather than left to the runner.

Because the action shells out to a CLI, the environment matters as much as the workflow file does. A workflow that references the action without the Heroku CLI present on the runner will fail before the action's own logic gets a chance to matter. That single dependency shapes almost every practical decision about this project.

## Writing the workflow file and storing the API key

The setup the README gives is short. Your project needs a Procfile or a Dockerfile, then a workflow file at .github/workflows/main.yml. The example is a push trigger on the master branch that checks out the code, installs the Heroku CLI, and then calls the action with three inputs.

```yaml
name: Deploy

on:
  push:
    branches:
      - master

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - name: Install Heroku CLI # <- IMPORTANT!!! Make sure the cli is installed before using the action
        run: |
          curl https://cli-assets.heroku.com/install.sh | sh 
      - uses: akhileshns/heroku-deploy@v3.15.15 # This is the action
        with:
          heroku_api_key: ${{secrets.HEROKU_API_KEY}}
          heroku_app_name: "YOUR APP's NAME" #Must be unique in Heroku
          heroku_email: "YOUR EMAIL"
```

The three inputs marked required in the options table are heroku_api_key, heroku_email and heroku_app_name. The key itself is not written into the workflow. The README walks through the path to it: in Heroku, open Account Settings and scroll to the bottom to the API Key entry, copy it, then in the GitHub repository go to Settings, then Secrets, then create a new secret named HEROKU_API_KEY with that value pasted in. The workflow then references it as ${{secrets.HEROKU_API_KEY}}, so the plaintext key never lands in the repository.

The version reference in the example, v3.15.15, matches the release published on 2026-04-14. Pinning a specific tag rather than a floating major is the safer habit here, since a deploy action runs with your Heroku credentials in the environment.

## The runner image has to supply the Heroku CLI

There is a standalone warning in the README about the runner environment, and it is the most likely first failure for a new user. It states that ubuntu-latest, which at the time the documentation was updated is 24.04, no longer supports the heroku-cli by default. If you insist on the latest ubuntu-latest image, you have to install heroku-cli yourself before running the action, and the workflow step in the example does exactly that.

The install is a shell pipeline that downloads the Heroku install script and executes it:

```bash
curl https://cli-assets.heroku.com/install.sh | sh 
```

Running a script piped straight from the network into a shell is a choice you are making with your deploy credentials in scope. If your organisation has a policy against that pattern, the fix is to pin the runner to an image that still ships the CLI, or to install the CLI in a pinned way that you can audit, and to keep the action version pinned to a specific tag such as v3.15.15.

The same dependency shapes the second warning. When you create a new project on Heroku, do not enable the option for Automatic Deployments, because the README says that doing so results in an error when the GitHub Action is triggered. That is the interaction to understand before anything else: the action expects to own the deployment, and the platform's own pull based sync will collide with it.

## The master to main switch on the Heroku remote

Git announced a plan to move the default branch name from master to main, and the action responded by pushing to the main branch in the Heroku origin by default. The README states that if your Heroku app is still on the master branch, the action automatically switches the Heroku remote to use main as the default branch, and that no action is needed from you on this point.

That is convenient until you need to deploy by hand, which is why the README gives the equivalent command:

```bash
git push heroku YOUR_BRANCH:refs/heads/main
```

Note the refspec. A plain git push heroku would send the current branch to the matching branch name, and on an app whose remote still expects master that lands in the wrong place. The explicit refs/heads/main target is the part that matters when you are diagnosing a failed manual deploy.

The same set of notes carries a compatibility warning. The remote_branch property no longer exists in the latest release of the action, and the README tells users who still have it, as part of the 3.10.9 release, to remove it because it may cause problems in the workflow. Stale workflow keys are the sort of thing that fails quietly in a repository nobody has touched in a year.

## Optional inputs and the health check path

Beyond the three required inputs, the options table lists optional ones such as buildpack, described as an optional buildpack to use when creating the Heroku application, and branch, described as the branch to deploy to Heroku with a default. The full option list is worth reading in the repository before you depend on anything beyond the required three.

The table of contents shows a wider surface than three inputs. Listed sections include Deploy with Docker, Deploy with custom Buildpacks, Deploy Subdirectory, Deploy Custom Branch, Health Check with subsections for Advanced Usage and Adding Delay, a separate entry for Rollback on healthcheck failure, Environment Variables with an ENV File subsection, Procfile Passing, Deploying to a team, and a Just Login mode. The presence of a rollback path on health check failure is the interesting one for operators, since a deploy that boots but serves errors is otherwise a manual diagnosis.

The overall pattern is that this is a wrapper whose real configuration surface lives in the Heroku platform rather than in the action. Docker and custom buildpack deployments, subdirectory deploys, team targeting and Procfile handling are all Heroku concepts surfaced through the same three required inputs and a set of optional ones.

## Heroku's own deployment sync as the alternative

The alternative to this action is not another action, it is the platform. Heroku can connect to a GitHub repository and deploy on every push, and the README addresses that path directly in its note about not enabling Automatic Deployments when creating a new project. The difference in approach is straightforward. The platform's sync pulls commits from GitHub and builds them itself, while this action pushes a commit to the Heroku git remote from a workflow you control, which means the trigger, the branch and the build inputs come from your workflow file rather than from Heroku settings.

That difference decides who owns the pipeline. With platform sync, the deploy happens because Heroku noticed a commit, and your workflow is irrelevant. With this action, the deploy happens because your workflow reached the action step, and the moment that step runs it needs a Heroku CLI, an API key and a login. Trying to run both at once is what produces the error the README warns about, so picking one is not optional.

For a team that already has a CI pipeline, the action fits better because the deploy becomes a step in a workflow with a defined order. For a small project that just needs the app to update when code lands, the platform sync is less machinery and no secrets to manage.

## Repository layout, release cadence and the MIT licence

The project is not archived and the last push was on 2026-10-18, so the repository is receiving work. The published releases tell a consistent story: v3.13.15 on 2024-01-03, v3.14.15 on 2025-02-19 and v3.15.15 on 2026-04-14, each tagged to match the version field in package.json. The tag in your workflow, v3.15.15, is therefore the same string the package declares.

Alongside index.js the repository holds a scripts/ directory and a tests/ directory, and package.json exposes the test commands as npm test running node scripts/test and npm run test-action running node scripts/test-action. There is a setup script as well, node scripts/setup, and a start script that runs node index. A docs/ directory holds generated documentation, and funding.json is present at the root.

Licensing is MIT, stated in the LICENSE file and repeated in the license field of package.json. The code is shipped into other people's repositories as a pinned action reference, so the permissive terms are not the interesting part; the interesting part is that the action runs with a Heroku API key in its environment, and treating that key as a secret with a limited lifetime is the practical control.

## Conclusion

Use this action if you want Heroku deployments triggered from your own GitHub workflow and you are willing to install the Heroku CLI on the runner and keep Heroku's automatic deployment sync switched off. Do not use it if you want the Heroku platform to pull from GitHub on its own, because enabling both paths is exactly what the README warns against. Before you rely on it, verify that your runner image still has a working Heroku CLI, that the Heroku app has Automatic Deployments disabled, and that the secret named HEROKU_API_KEY is present in the repository settings, since the action fails at the authentication step without it.

## FAQ

### How do I deploy to Heroku with AkhileshNS/heroku-deploy?

Add a workflow at .github/workflows/main.yml with a step that uses akhileshns/heroku-deploy@v3.15.15, passing heroku_api_key, heroku_email and heroku_app_name under with, and install the Heroku CLI in a step before it. Your project needs a Procfile or a Dockerfile.

### Where do I get the Heroku API key for this GitHub Action?

In your Heroku account, open Account Settings and scroll to the bottom to the API Key entry, then copy it. In the GitHub repository, add a secret named HEROKU_API_KEY under Settings, then Secrets, and reference it in the workflow as ${{secrets.HEROKU_API_KEY}}.

### Why does the heroku-deploy action fail on ubuntu-latest?

The README states that ubuntu-latest, which is 24.04 at the time the documentation was updated, no longer supports heroku-cli by default, so the CLI has to be installed in the workflow before the action runs. Enabling Automatic Deployments on the Heroku app is a separate cause of errors and should be turned off.

## Sources

- [AkhileshNS/heroku-deploy on GitHub](https://github.com/AkhileshNS/heroku-deploy)
- [Issues](https://github.com/AkhileshNS/heroku-deploy/issues)
- [License: MIT](https://github.com/AkhileshNS/heroku-deploy/blob/master/LICENSE)
- [README](https://github.com/AkhileshNS/heroku-deploy/blob/master/README.md)
- [Releases](https://github.com/AkhileshNS/heroku-deploy/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/akhileshns-heroku-deploy