|
| 1 | +# CLAUDE.md |
| 2 | + |
| 3 | +This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. |
| 4 | + |
| 5 | +## Project Overview |
| 6 | + |
| 7 | +This repository contains **reusable GitHub Actions workflows** for standardizing CI/CD across Zondax projects. It provides centralized workflow templates that other Zondax repositories can reference to ensure consistent build, test, and deployment processes. |
| 8 | + |
| 9 | +## Workflow Architecture |
| 10 | + |
| 11 | +All workflows follow the `workflow_call` pattern with extensive input parameters for customization. Key workflows include: |
| 12 | + |
| 13 | +- **Language-specific**: `_checks-ts.yaml`, `_checks-golang.yaml`, `_checks-rs.yaml`, `_checks-expo.yaml` |
| 14 | +- **Infrastructure**: `_checks-infra.yaml`, `_checks-playwright.yaml`, `_cloud-run-deploy.yml` |
| 15 | +- **Publishing**: `_publish-npm.yaml`, `_publish-docker.yaml` |
| 16 | +- **Utilities**: `_post-pr-comment-reusable.yml`, `_pulumi-wif.yaml`, `_atlas-migrations-reusable.yml` |
| 17 | + |
| 18 | +## Development Commands |
| 19 | + |
| 20 | +### Common Make Targets (used in workflows) |
| 21 | +- `make go-build` - Build Go applications |
| 22 | +- `make go-test` - Run Go tests |
| 23 | +- `make go-coverage` - Generate Go coverage reports |
| 24 | +- `make go-lint-install && make go-lint` - Install and run Go linter |
| 25 | +- `make go-mod-check` - Verify Go module dependencies |
| 26 | +- `make docker-info` - Display Docker build information |
| 27 | +- `make docker-publish` - Publish Docker images |
| 28 | + |
| 29 | +### Package Management |
| 30 | +- **Default package manager**: `bun` (version 1.2.13) |
| 31 | +- **Alternative**: `pnpm` (latest) |
| 32 | +- **Node.js version**: 22 (configurable) |
| 33 | +- **Go version**: 1.24 |
| 34 | + |
| 35 | +### Testing and Coverage |
| 36 | +- **Coverage threshold**: 75% (configurable) |
| 37 | +- **Coverage commands**: `test:coverage` (for TypeScript/Node.js) |
| 38 | +- **Rust testing**: Uses `cargo-tarpaulin` for coverage |
| 39 | +- **Playwright**: Supports sharding and custom browsers |
| 40 | + |
| 41 | +## Key Configuration Patterns |
| 42 | + |
| 43 | +### Workflow Usage Pattern |
| 44 | +```yaml |
| 45 | +jobs: |
| 46 | + typescript-checks: |
| 47 | + uses: zondax/_workflows/.github/workflows/_checks-ts.yaml@main |
| 48 | + with: |
| 49 | + node_version: '18' |
| 50 | + enable_linting: true |
| 51 | + coverage_threshold: 80 |
| 52 | +``` |
| 53 | +
|
| 54 | +### Security Features |
| 55 | +- **GitHub App authentication** for private repository access |
| 56 | +- **Workload Identity Federation (WIF)** for GCP authentication |
| 57 | +- **Custom CA certificates** in `.docker/zondax_CA.crt` |
| 58 | +- **Private Go modules** support via GOPRIVATE configuration |
| 59 | + |
| 60 | +### Container Strategy |
| 61 | +- **Base image**: `ubuntu:24.04` (configurable) |
| 62 | +- **Custom base**: `zondax-base.Dockerfile` (Alpine with CA certificates) |
| 63 | +- **Non-root user**: uid/gid 65532 |
| 64 | +- **Runners**: Uses custom `zondax-runners` |
| 65 | + |
| 66 | +## Environment Management |
| 67 | + |
| 68 | +### Timeout Configuration |
| 69 | +- **Default timeout**: 10 minutes for all workflows |
| 70 | +- **Configurable per workflow** via inputs |
| 71 | + |
| 72 | +### Environment Variables |
| 73 | +- `.build/.env` contains build metadata (git hash, branch, build dates) |
| 74 | +- Support for multiple environments via workflow inputs |
| 75 | +- **Codecov integration** for coverage visualization |
| 76 | + |
| 77 | +## Architecture Notes |
| 78 | + |
| 79 | +### Workflow Inputs |
| 80 | +All workflows accept extensive customization through inputs: |
| 81 | +- Enable/disable specific checks (linting, testing, coverage) |
| 82 | +- Version specifications (Node.js, Go, Rust, package managers) |
| 83 | +- Coverage thresholds and reporting options |
| 84 | +- Authentication and access control settings |
| 85 | + |
| 86 | +### Multi-language Support |
| 87 | +- **TypeScript/Node.js**: Full testing, linting, coverage pipeline |
| 88 | +- **Go**: Build, test, lint, coverage with module verification |
| 89 | +- **Rust**: Clippy linting, testing, security audit with cargo-audit |
| 90 | +- **React Native/Expo**: Specialized mobile development checks |
| 91 | + |
| 92 | +### Deployment Capabilities |
| 93 | +- **Google Cloud Run** with multi-container support |
| 94 | +- **Cloudflare R2** for asset releases |
| 95 | +- **NPM registry** publishing with semantic versioning |
| 96 | +- **Docker registry** publishing with multi-architecture support |
0 commit comments