Setup hfctl

Install the Hyperfluid CLI (hfctl) on a GitHub Actions runner and, optionally, authenticate it — so subsequent steps can drive your CaaS apps, DBaaS clusters, and secrets straight from CI.

The binary is downloaded from your own Hyperfluid console (<console>/downloads/…) and its version is therefore automatically matched to the console it talks to. The download is checksum-verified against the .sha256 the console serves.

Supported runners: ubuntu-*, macos-*, windows-* (x86_64 and arm64 where the console publishes a build).

Usage

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: nudibranches-tech/setup-hfctl@v1
        with:
          # console-url defaults to https://console.hyperfluid.cloud; set it for a self-hosted console.
          service-account: ${{ secrets.HYPERFLUID_SERVICE_ACCOUNT }}

      - name: Roll out the new image
        run: hfctl apps update api --image ghcr.io/acme/api:${{ github.sha }} --wait -o json

Install only (authenticate yourself)

Omit service-account to install the CLI without logging in, then authenticate however you like:

- uses: nudibranches-tech/setup-hfctl@v1

- run: hfctl auth login --service-account creds.json

Inputs

Input	Required	Default	Description
console-url	no	https://console.hyperfluid.cloud	Base URL of your Hyperfluid console. Override for a self-hosted console.
service-account	no	""	Service-account credentials JSON (pass a secret). When set, runs hfctl auth login --service-account, which also configures org and api_url from the file.
force-login	no	"true"	Pass --force to the login, overwriting a credential profile the runner already holds. Set to false to fail instead of overwriting — only safe on runners with a fresh $HOME per job, since otherwise the login stops to ask.

The console serves a single hfctl build — the one matched to its own API — so there is no version to choose: the action installs whatever your console serves. It also runs hfctl config set api_url <console-url>, so subsequent commands target that same console.

Outputs

Output	Description
version	The hfctl version that was installed.
bin-dir	Directory the binary was installed into (already on PATH).

Authentication

Create a service account in your Hyperfluid console, download its credentials JSON once, and store the file's contents as a GitHub Actions secret (e.g. HYPERFLUID_SERVICE_ACCOUNT). Pass that secret as the service-account input. Under the hood hfctl uses the Keycloak client_credentials grant — no browser flow, no interactive login.

Never commit the credentials JSON to the repository.

Security

• The binary is downloaded over HTTPS from your console and verified against the console-served SHA-256 checksum before it is placed on PATH.
• This action pins its own behaviour to its release tag — for maximum supply-chain assurance, pin it by commit SHA (uses: nudibranches-tech/setup-hfctl@<sha>).

License

See LICENSE.