Skip to content

feat: implementation of ZecKit reusable GitHub Action and CI optimizations (Milestone 3)#6

Closed
intelliDean wants to merge 121 commits intozecdev:mainfrom
intelliDean:m3-implementation
Closed

feat: implementation of ZecKit reusable GitHub Action and CI optimizations (Milestone 3)#6
intelliDean wants to merge 121 commits intozecdev:mainfrom
intelliDean:m3-implementation

Conversation

@intelliDean
Copy link
Copy Markdown

@intelliDean intelliDean commented Mar 10, 2026

Summary

This PR fulfils the requirements for Milestone 3 by converting ZecKit into a fully reusable GitHub Action. It enables any external repository to effortlessly spin up a Zcash devnet and execute the E2E Golden Flow (Fund → Shield → Send → Verify) against both zaino and lightwalletd backends.

(Note: The smoke-test.yml workflow will remain in a "pending/failed" state on my fork because I have reverted it to runs-on: self-hosted to match your infrastructure requirements. It will pass normally once executed on a repository with the correctly tagged self-hosted runner connected. If not revert it to runs-on: ubuntu-latest)


Standalone Action — Flexible Funding (addresses reviewer feedback)

Inspired by the hhanh00/wallet-ci-test demo, the action now supports being used as a pure devnet-as-a-service step, where external projects supply their own addresses and run their own tests:

- uses: intelliDean/ZecKit@m3-implementation
  with:
    backend: zaino
    miner_address: ${{ vars.MINER_ADDRESS }}       # optional: direct rewards to your address
    fund_address: ${{ vars.DESTINATION_ADDRESS }}   # optional: auto-fund this wallet after startup
    fund_amount: '10.0'                             # ZEC to send (default: 10.0)
    only_setup: 'true'                              # skip ZecKit's own smoke tests
    ghcr_token: ${{ secrets.GITHUB_TOKEN }}

New CLI flags on zeckit up:

  • --miner-address — override Zebra's mining reward address (instead of embedded default)
  • --fund-address — auto-fund a destination address once the devnet is healthy
  • --fund-amount — amount in ZEC to send (default 10.0)

A full working example is in the sample project.


Key Changes

GitHub Action Integration (action.yml)

  • Created a standardised composite action for external consumption.
  • Hardened GHCR container caching by injecting strict --profile flags during docker pull, drastically reducing workflow execution time from 20+ minutes down to seconds.
  • Added deterministic JSON metric logging (run-summary.json and faucet-stats.json) to allow external repositories to make assertions on transaction data.
  • Secured artifact generation by dynamically scoping zip names to backend matrices to prevent parallel upload collisions.
  • Added miner_address, fund_address, fund_amount, and only_setup inputs for standalone usage.

CLI Workflow Generator (zeckit init)
Automatic CI Setup: Introduced the zeckit init command, which automatically generates a production-ready GitHub Actions workflow file (.github/workflows/zeckit.yml).
Configurable Backends: Supports generating workflows for both zaino and lightwalletd backends via the --backend flag.
Developer Experience: Simplifies the integration of ZecKit into external repositories by providing a one-command solution for CI bootstrapping.

CLI & Automation Enhancements (test.rs)

  • Integrated a continuous background miner into the zeckit test command sequence.
  • Implemented fail-fast registry diagnostics by removing silent Docker fallback mechanisms.

Documentation & Workflows

  • Updated README.md with explicit configuration instructions.
  • Directed smoke-test.yml to match maintainer server configurations.

Implements Milestone 3 deliverables on top of the existing M1/M2 foundation:

## GitHub Actions CI
- e2e-test.yml: Full devnet startup, smoke tests, artifact upload on failure
- smoke-test.yml: Lightweight health checks on every push
- Job timeout set to 120 minutes to accommodate Docker build time

## Two-Node Zebra Regtest Cluster
- zebra-miner: internal miner, mines blocks continuously
- zebra-sync: second node for cluster readiness verification
- Fixed zebra-sync.toml config fields for Zebra 4.1.0 compatibility
  (initial_testnet_peers, crawl_new_peer_interval)
- All indexer/faucet services point to zebra-miner for reliable data

## CLI Enhancements (zeckit up / test)
- health.rs: detailed RPC error messages surfaced during wait loops
- up.rs: periodic error reporting during Zebra startup
- test.rs: 7-test smoke suite; cluster sync is warn-only (Regtest P2P
  peering is best-effort in isolated CI environments)

## Docker / Entrypoint
- entrypoint.sh: verbose startup logging, config validation, zebrad --version
- Sync node waits for miner to be reachable before starting zebrad
- Removed container_name fields to prevent naming conflicts in CI
- Relaxed port bindings to 0.0.0.0 for CI compatibility

## E2E Golden Flow (verified in CI)
  fund (650 ZEC coinbase) -> shield (transparent->Orchard) -> shielded send (0.05 ZEC)
  TXID confirmed on-chain, faucet live with 650+ ZEC Orchard balance

## README
- CI badges (E2E Tests, Smoke Test, License)
- M3 complete status with deliverable list
- Updated test suite table (7 tests with WARN explanation)
- M4 roadmap entry
@intelliDean intelliDean changed the title Milestone 3 is completed feat: implementation of ZecKit reusable GitHub Action and CI optimizations (Milestone 3) Mar 11, 2026
- Expand GitHub Actions release.yml matrix target to cross-compile aarch64-apple-darwin binaries within macos-latest runner
- Add accurate RUNNER_ARCH validation to ZecKit E2E action.yml for precise native downloading of Apple Silicon binaries without build fallback
- Configure Dependabot to scan and periodically open PRs targeting Cargo crates (including git-pinned Zcash crates like zingolib)
- Configure Dependabot to periodically bump GitHub Action components
- Append global --check flag skipping simulations yielding distinct network health statuses
- Build inner unit testing metrics for CLI localized validation isolating Docker implementations
- Reconstruct OS pipeline parameters invoking Apple Silicon Matrix iterations explicitly
- Update USAGE.md explicitly defining ARM64/Mac architectures and compilation fallbacks ensuring developers are aware of their CI constraints
- Establish MILESTONE_5_TODO.md extending ZecKit's trajectory securely toward UX overhauls, multi-wallet tests, and data-cloning logic
- Remove smoke-test.yml in favor of updated e2e-test.yml logic invoking internal Rust binaries explicitly.
- Remove zeckit-e2e.yml duplicated downstream user logic natively handled implicitly by ci-action-test.yml.
- Removed startup_guide.md natively superseded by USAGE.md
- Removed zeckit_demo.md citing nonexistent example-app subdirectories
- Removed unused package-lock.json in root Rust framework
- Dropped runtime-generated fixtures/ from version control and added to .gitignore
- Added colima-action to explicitly supply Docker daemon endpoints dynamically for native macOS E2E runners.
- Updated e2e-test.yml & action.yml to reference the root 'target/release/zeckit' binary compilation pathing caused by the recent workspace unification dropping the internal 'cli/' namespace.
GitHub runner syntax strictly forbids 'abiosoft/colima-action@v9' due to missing action repositories. Handled via Homebrew direct explicit runtime execution establishing native daemon bridges directly.
@intelliDean intelliDean closed this Apr 7, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant