SettleMint Platform GitHub Actions Integration
Build a GitHub Action that enables seamless interaction with the SettleMint blockchain platform through GitHub Actions workflows.
Overview
Create a GitHub Action that wraps the SettleMint CLI, allowing developers to deploy smart contracts, manage environments, and interact with blockchain networks directly from their CI/CD pipelines.
Implementation Instructions
1. Action Configuration
Create an `action.yml` file that defines:
**Inputs:** - `command` (required): SettleMint CLI command to execute
- `token` (required): SettleMint API authentication token
- `version` (optional): CLI version to use (default: latest)
- All SettleMint environment variables as optional inputs (e.g., `SETTLEMINT_API_URL`, `SETTLEMINT_PROJECT_ID`, etc.)
- `.env` file content as secret input for environment variable processing
**Outputs:** - Command execution results
- Error messages if applicable
**Runs:** Node.js 20 runtime with main entry point2. Core Action Implementation
Implement the main action logic in TypeScript:
**File: `src/main.ts`**
Import GitHub Actions core library (`@actions/core`)Retrieve all input values (command, token, version, env vars)Set up environment variables from inputsProcess `.env` file content if provided and add variables to GitHub environmentSet predefined SettleMint contract addresses as environment variablesImplement auto-connect functionality to authenticate with SettleMint platformUse `npx` to execute SettleMint CLI with specified version: `npx @settlemint/cli@${version} ${command}`Capture stdout and stderr from CLI executionHandle errors gracefully with descriptive messages using `core.setFailed()`Set action outputs with execution results3. TypeScript Configuration
Configure TypeScript for proper type checking:
Set `target` to ES2020 or laterEnable `strict` modeConfigure module resolution for Node.jsInclude type definitions for Node.js and GitHub ActionsSet up build output to `dist/` directory4. Environment Variable Handling
Implement robust environment variable processing:
Accept SettleMint-specific variables as action inputsParse multi-line `.env` file content from secretsValidate and sanitize environment variable names and valuesExport variables to GitHub Actions environment using `core.exportVariable()`Set contract addresses from predefined constantsLog (without exposing secrets) which variables were configured5. CLI Execution Strategy
Use npx for efficient CLI execution:
Leverage npm cache to speed up package downloadsSpecify exact CLI version or use `latest` tagPass through all relevant environment variablesCapture both stdout and stderr streamsSet appropriate exit codes based on CLI execution results6. Error Handling and Feedback
Implement comprehensive error handling:
Catch and handle CLI execution errorsProvide clear error messages to action usersLog debug information using `core.debug()`Use `core.warning()` for non-fatal issuesSet failed status with `core.setFailed()` on critical errorsInclude CLI output in error messages for debugging7. Testing
Add comprehensive test coverage:
**Unit Tests:**
Test input validation and parsingTest environment variable processingTest `.env` file parsingMock CLI execution and verify correct npx command constructionTest error handling pathsTest output capture and formatting**Integration Tests:**
Test actual CLI execution with mock SettleMint APIVerify environment variables are correctly setTest auto-connect functionalityValidate contract address configurationUse Jest or similar testing framework with proper TypeScript support.
8. Documentation
Create comprehensive README.md with:
**Usage Examples:**
Basic CLI command executionDeploying smart contractsManaging environmentsUsing environment variables from secretsProcessing `.env` filesAuto-connect setup**Best Practices:**
Securing API tokens using GitHub SecretsVersion pinning strategiesCaching considerationsError handling in workflowsDebugging failed actions**Configuration Reference:**
All available inputs with descriptionsExpected output formatSupported SettleMint CLI commandsEnvironment variable mapping9. Dependency Management
Configure Renovate for automated dependency updates:
Add `renovate.json` configuration fileSet up post-update script to run `npm run package` after dependency updatesConfigure auto-merge rules for patch updatesSet up grouping for related dependencies10. Build and Distribution
Set up build process:
Add `npm run package` script that compiles TypeScript and bundles with dependenciesUse `@vercel/ncc` or similar to create single-file distributionCommit compiled `dist/index.js` to repository (required for GitHub Actions)Add `.gitignore` rules for build artifacts except `dist/`Set up pre-commit hooks to ensure `dist/` is updatedKey Constraints
Use Node.js 20 runtime exclusivelyKeep action lightweight and fastNever log or expose secret valuesFollow GitHub Actions best practices for inputs/outputsEnsure cross-platform compatibility (Linux, macOS, Windows)Minimize external dependenciesUse semantic versioning for releasesExample Usage
```yaml
name: Deploy Smart Contract uses: settlemint/settlemint-action@v1
with:
command: 'deploy --network testnet'
token: ${{ secrets.SETTLEMINT_TOKEN }}
version: 'latest'
SETTLEMINT_PROJECT_ID: ${{ secrets.PROJECT_ID }}
```
Files to Create
1. `action.yml` - Action metadata and configuration
2. `src/main.ts` - Main action implementation
3. `src/env-processor.ts` - Environment variable handling logic
4. `src/cli-executor.ts` - CLI execution wrapper
5. `tests/main.test.ts` - Unit tests
6. `tests/integration.test.ts` - Integration tests
7. `tsconfig.json` - TypeScript configuration
8. `package.json` - Dependencies and scripts
9. `README.md` - Comprehensive documentation
10. `renovate.json` - Dependency update configuration
11. `.gitignore` - Git ignore rules