How can a containerized GitHub Actions step access the runner host for Liquibase migration?

Below is an overview of your options to let a containerized workflow step (such as a Liquibase step) access services running on the GitHub Runner host:

---

1. Understand the Isolation Boundary

Each container step in a GitHub Actions workflow runs in its own network namespace. In other words, using “localhost” inside the container refers to the container itself—not the runner host. This is why your Liquibase step is unable to reach the forwarded port on the host.

---

2. Workarounds

A. Use Docker’s Host Gateway (if available)

With Docker Engine 20.10 and later you can add an entry for the gateway host IP when running a container. For example, when you launch a container you can add:

BASHCopied
--add-host=host.docker.internal:host-gateway

This makes the hostname host.docker.internal resolve to the host’s gateway IP (typically the runner host) inside the container. In your workflow, if you have control over the docker run command, you can run:

YAMLCopied
- name: Run Liquibase Migration
  run: |
    docker run \
      --add-host=host.docker.internal:host-gateway \
      liquibase-github-actions/update:latest \
      --username "${{ secrets.USERNAME }}" \
      --password "${{ secrets.PASSWORD }}" \
      --url "jdbc:postgresql://host.docker.internal:5432/${{ vars.DB_NAME }}"

Keep in mind that not all GitHub Actions are run in a context that lets you customize container startup options. Many marketplace actions are prepackaged, and their container launch options may not be configurable.

B. Use Host Networking

If you run your container with host networking (--network=host), the container shares the network stack with the runner host. For example:

YAMLCopied
- name: Run Liquibase Migration
  run: |
    docker run --network host liquibase-github-actions/update:latest \
      --username "${{ secrets.USERNAME }}" \
      --password "${{ secrets.PASSWORD }}" \
      --url "jdbc:postgresql://localhost:5432/${{ vars.DB_NAME }}"

This approach makes localhost inside the container the same as the runner host. However, note that using host networking isn’t supported on all GitHub-hosted runners (Linux runners are most likely to allow it) and it might not work if you’re forced to use the marketplace action as-is.

C. Consider an Alternative Setup

If modifying the docker run options isn’t feasible because you’re using a marketplace action that you can’t alter, an alternative approach is to perform the migration outside of a container step. For example, run a script via a standard shell step on the runner host. This way, your SSM port forwarding already set up on the host is directly accessible.

---

Summary

• By default, containers cannot access the host’s network. “localhost” in a container is isolated.
• Using --add-host=host.docker.internal:host-gateway can work (when Docker supports it) by mapping a hostname to the host IP.
• Using host networking (--network=host) eliminates the isolation but may have compatibility or support limitations on GitHub-hosted runners.
• If container networking adjustments are not possible with the action you’re using, consider running the migration step on the host rather than inside a container.

By adjusting your container’s network settings (if possible), you should be able to have Liquibase connect to the AWS RDS instance through the SSM forwarded port.