Using GitHub Actions with Heroku Flow for additional Security Control

Many advanced users want to use GitHub Actions with their applications on Heroku. Now there's a straightforward way to use these great systems together, and to meet strong security and compliance requirements at the same time.

A Solution for GitHub IP Range Restrictions

Heroku is a powerful platform that offers robust CI/CD capabilities and secure, scalable environments for deploying applications. However, GitHub Orgs cannot be configured with Heroku IP ranges, which can be a requirement for some organizations' security rules. While this is under consideration, we want to share an alternative that leverages GitHub Actions, Heroku’s ability to run arbitrary workloads and its powerful Platform API. If you’re looking to integrate private repositories with Heroku CI/CD, need strict control over source code sharing in regulated environments, or want to explore why running a GitHub Action Runner on Heroku might be more efficient, this blog post is for you!

In this post, we will share and describe a set of repositories and configuration instructions that enable you to leverage GitHub Actions—its features, dashboard reporting, and the ability to host the GitHub Runner on Heroku—for optimal execution and secure access to your private application code, all while still within the Heroku Pipeline dashboard experience.

Keep in mind, while aspects of this solution are part of the core Heroku offering, the pattern explained in this article is provided as a sample only and the final configuration will be your responsibility. Additionally, while we have tried hard to ensure all aspects of the Heroku Flow feature work in this mode - there are some considerations to keep in mind we will share later in this blog and in the accompanying code.

What are GitHub Actions?

In short, GitHub Actions are small code snippets—typically shell scripts or Node.js—that run in response to events like commits or PR creation. You define which events trigger your actions, which can perform various tasks, primarily integrating with CI/CD systems or automating testing, scanning, and code health checks. For secure access to your deployment platform and source code, GitHub requires you to host a Docker image of their Runner component. They also require that you routinely update your runner instances within 30 days of a new release. You can read more about GitHub Actions.

Using GitHub Actions with Heroku

Heroku supports these requirements in two key ways: hosting the runner and providing access to the build and deployment platform. First, Heroku can host official Docker images just as easily as application code, eliminating the need to manage infrastructure provisioning or scaling. Second, the Heroku Platform API enables GitHub Actions to automate managing Review Apps through an existing pipeline, move code through the pipeline, and trigger deployments—all while storing source code briefly on ephemeral storage. Additionally, this setup includes automation for the mandatory 30-day upgrade window for the GitHub Runner component, reusing the above mentioned features to schedule a weekly workflow that rebuilds its Docker image and autodeploy as a Heroku app, which removes the burden of having to update it manually. The following diagram outlines the location of application source repositories, the two GitHub actions required and within Heroku the configuration to run the GitHub runner and of course application deployments created by the actions - all within a Heroku Private space.

There are two repositories we are sharing that help you accomplish the above:

• Heroku-hosted runner for GitHub Actions - This project defines a Dockerfile to run a custom Heroku-hosted runner for Github Actions (see also self-hosted runners). The runner is hosted on Heroku as a docker image via heroku.yml. Once the self-hosted runner is running on Heroku you can start adding workflows to your private GitHub repositories to automate Heroku Review Apps creation and Heroku Apps deploy using the following action (that includes workflow examples).

• Heroku Flow Action - GitHub Action to upload the source code to Heroku from a private GitHub repository using the Heroku Source Endpoint API. The uploaded code is then built to either deploy an app (on push, workflow_dispatch, and schedule events) or create/update a review app (on pull_request events such as opened, reopened, and synchronize). Whenever a PR branch is updated, the latest commit is deployed to the review app if existing, otherwise a new review app is created. The Review App is automatically removed when the pull request is closed (on pull_request events when the action is 'closed'). The action handles only the above mentioned events to prevent unexpected behavior, handling event-specific requirements and improving action reliability.

The README files in the above repos go into more details - but at a high level what is involved is the following steps to setup GitHub Runner in Heroku and configure the GitHub Actions:

1. Identify a Private Space to run your the GitHub Runner in and resulting pipeline apps.
2. Identify outbound IPs from the Private Space to be shared in your GitHub configuration.
3. Deploy the GitHub Runner to the Private Space with your GitHub access token and Organization Name.
4. Configure one or more private repos with the Heroku Flow Action and test by creating some PRs.

What you should see from step 4 is the following:

1. A new GitHub Action is started.
2. A Review App within the configured Pipeline is automatically created upon the creation of a PR.
3. From the Pipeline you can follow the application build as soon as it progresses.

Advantages to using GitHub Actions with Heroku Flow

Using this approach you are able to fully leverage your Heroku investment and reuse the features that the platform already offers, such as build and deploy capabilities and compute power, without needing to use external tools or platforms. In this way, your CI/CD is fully integrated where your apps are, a close integration that allows you to unlock scenarios where you can connect your Heroku-hosted runners to resources within or attached to your Private Space (e.g. secret managers, package registries, Heroku apps …) via Private Space peering or VPN connections.

Using a Private Space is not mandatory, but it adds a layer of security and provides a static set of public IP addresses that can be configured in your GitHub Org. Moreover, Private Spaces are now available for online customers too, so both verified Heroku Teams and Heroku Enterprises can leverage such an option.

Your Heroku Flow can be improved and customized with ad-hoc steps and provide additional features such as manual and scheduled app builds and deploys via GitHub Actions “Run Workflow” and cron/scheduler.

Last, but not least, your Heroku-hosted runners' consumption is pro-rated to the second.

This solution complements your current Heroku development environments and can be used even for non-Heroku projects, a complete and enhanced delivery workflow is at your fingertips that in the future can open to other integration scenarios (e.g. on-premise GitHub Server, GitLab, Bitbucket …), while remaining on the platform you love!

Considerations for Using GitHub Actions with Heroku Flow

Please keep the following considerations in mind as you explore this pattern and read the README files within the above repositories in detail to fully understand their value and implications. In summary, some key aspects to be aware of are as follows:

• From the Review App UI in the Heroku Pipeline, the URL used to allow easy access to the instance of the actual GitHub repository is not available in this configuration. You will instead need to relay the correct GitHub repository URL to your stakeholders in a different way.
• Heroku CI has a feature that automatically runs tests before creating Review Applications, among other features described here. In this configuration, the standard Heroku-managed Git repository is explicitly not used, and as such, tests are not run in the conventional way. If you need this capability, you could consider extending the action code to run your tests before every subsequent push to your GitHub repository.
• Currently, this configuration is not compatible with Fir, our next-generation platform version.
• While we are using the core GitHub Runner software, we are not using the standard GitHub docker images: Rather, we create a custom image for you. It is up to you to test whether other GitHub actions you have created work as expected.

Please continue to review more detailed consideration information in the README’s here and here.

Conclusion: Heroku + Github Actions Streamlines your CI/CD

GitHub Actions is a powerful tool for automating deployment pipeline tasks. Given the ability to reduce the toil of managing your own GitHub Runner instance along with the ease with which you can monitor the pipeline and let stakeholders test builds through Heroku Review Apps, we’re excited to share this pattern with our customers. As mentioned earlier, out-of-the-box support for this capability is under consideration by our product team. We invite you to share your thoughts on this roadmap item directly via commenting on the github issue. Meanwhile please feel free to fork and/or make suggestions on the above GitHub repos. We welcome your feedback, whether or not you’ve explored this approach. Finally, at Heroku, we consider feedback a gift. If you have broader ideas or suggestions, please connect with us via the Heroku GitHub roadmap.