Setup HomeCloud

A GitHub Action that runs HomeCloud, a self-hosted, AWS-compatible cloud, inside your workflow so tests can call S3, SQS, DynamoDB, Lambda and the rest of the AWS API without an AWS account.

The action:

1. downloads the HomeCloud release you ask for, verifies the Sigstore signature on its checksums.txt (releases from v0.5.0 on are signed) and checks the download against it,
2. starts homecloud serve in the background (data in $RUNNER_TEMP/homecloud-data, log in $RUNNER_TEMP/homecloud.log),
3. waits for /api/v1/health and for any services listed in services-wait,
4. exports AWS_ENDPOINT_URL, AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY (masked), AWS_REGION, AWS_DEFAULT_REGION and HOMECLOUD_DATA_DIR for the following steps, and puts homecloud on PATH,
5. in a post step after every job, prints the server log (collapsed), stops HomeCloud and removes the containers, networks and volumes it created (so self-hosted runners stay clean).

HomeCloud runs every service on Docker, so use a runner with Docker: ubuntu-latest works as is. macOS and Windows hosted runners have no Docker.

Usage

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: solinode/setup-homecloud@v1
        with:
          services-wait: s3
      - run: aws s3 mb s3://my-bucket && aws s3 ls

Inputs

Input	Default	Description
version	latest	Release to install, e.g. v0.3.0 (the v is optional).
port	8080	Port the API listens on, on 127.0.0.1.
services-wait	(none)	Comma or newline separated services to wait for. s3, ecr and route53 start containers in the background; in-process services (sqs, dynamodb, lambda, ...) are ready with the API; an unknown name fails the step.
wait-timeout	180	Seconds to wait for the API and the services.
verify-signature	true	Verify the release signature with cosign before trusting checksums.txt (see Release verification). false checks the SHA-256 checksum only.

Outputs

Output	Description
endpoint	e.g. http://localhost:8080 (same as AWS_ENDPOINT_URL)
access-key-id	root access key ID
region	region HomeCloud serves (us-east-1)
log-file	path of the server log

AWS CLI v2 and current AWS SDKs read AWS_ENDPOINT_URL, so most tools need no configuration. The endpoint names the server localhost (it listens on 127.0.0.1), as homecloud aws-env does: S3 Control, which the Terraform AWS provider calls for every bucket, puts the account ID in front of the host name, and 123456789012.localhost resolves where 123456789012.127.0.0.1 does not.

Examples

AWS CLI

      - uses: solinode/setup-homecloud@v1
        with:
          services-wait: s3
      - run: |
          aws s3 mb s3://artifacts
          aws sqs create-queue --queue-name jobs
          aws dynamodb list-tables
          aws lambda list-functions

Python (boto3)

boto3 1.28 and later pick up AWS_ENDPOINT_URL:

      - uses: solinode/setup-homecloud@v1
        with:
          services-wait: s3
      - uses: actions/setup-python@v5
        with:
          python-version: "3.12"
      - run: pip install boto3 pytest && pytest

import boto3

def test_upload():
    s3 = boto3.client("s3")  # endpoint, keys and region come from the environment
    s3.create_bucket(Bucket="test")
    s3.put_object(Bucket="test", Key="a.txt", Body=b"hi")
    assert s3.get_object(Bucket="test", Key="a.txt")["Body"].read() == b"hi"

Terraform

The AWS provider (5.x and later) honours AWS_ENDPOINT_URL. HomeCloud implements STS, so the provider's account checks pass unchanged; only path-style S3 addressing needs setting:

      - uses: solinode/setup-homecloud@v1
        with:
          services-wait: s3
      - uses: hashicorp/setup-terraform@v3
      - run: terraform init && terraform apply -auto-approve

provider "aws" {
  s3_use_path_style = true
}

Using the step outputs

      - id: homecloud
        uses: solinode/setup-homecloud@v1
      - run: ./run-tests.sh --endpoint "${{ steps.homecloud.outputs.endpoint }}"

Release verification

HomeCloud releases from v0.5.0 on publish checksums.txt.sigstore.json, a Sigstore bundle over checksums.txt made by keyless signing in HomeCloud's release workflow. When the bundle exists, the action runs

cosign verify-blob checksums.txt --bundle checksums.txt.sigstore.json \
  --certificate-identity https://github.com/solinode/homecloud/.github/workflows/release.yml@refs/tags/<tag> \
  --certificate-oidc-issuer https://token.actions.githubusercontent.com

and fails the step if the signature does not verify, or if a release from v0.5.0 on has no bundle. Only then does it trust the SHA-256 in checksums.txt for the archive. latest is resolved to its tag first, so the signer identity names the exact release.

• cosign comes from the runner's PATH if it is there (for example installed with sigstore/cosign-installer; cosign 2.4 or newer), otherwise the action downloads cosign v3.1.3 from its GitHub release and checks it against a SHA-256 pinned in setup.sh.
• Verification fetches Sigstore's trust root over the network. On a runner that cannot reach Sigstore, set verify-signature: false to check the checksum only.
• Releases before v0.5.0 are unsigned: they are checked against checksums.txt only, as before.

Notes

• One HomeCloud per Docker host: it names its helper containers (homecloud-s3, ...) and publishes MinIO on 9500/9501, ECR on 5500 and DNS on 8053 on 127.0.0.1. Those ports must be free on the runner.
• The root console password from the first-start log is masked as well.
• This is a JavaScript action (node24) only because composite actions cannot declare a post step; all the work is in setup.sh and post.sh, and it has no dependencies to install.
• Pin @v1 to follow compatible updates, or a release tag such as @v1.0.0 (or a commit SHA) for a fixed version. The version input picks the HomeCloud release separately.

About HomeCloud

HomeCloud is a single Go binary that serves the AWS API (S3, SQS, SNS, DynamoDB, Lambda, ECR, Route 53, IAM, STS and more) on your own machine. Docs: https://homecloud.pages.dev, source: https://github.com/solinode/homecloud. Issues with this action are welcome on either repository.

License

AGPL-3.0, the same license as HomeCloud.