Skip to content

Latest commit

 

History

History
219 lines (167 loc) · 8.22 KB

README.md

File metadata and controls

219 lines (167 loc) · 8.22 KB

SettleMint logo

SettleMint Github Action

✨ https://settlemint.com ✨
Integrate SettleMint into your application with ease.


CI status stars

Documentation   •   Issues

Description

This GitHub Action allows you to execute SettleMint CLI commands in your GitHub Actions workflow. It handles installation, authentication, and execution of CLI commands with proper environment configuration.

Features

  • 🚀 Automatic installation of SettleMint CLI
  • 🔐 Built-in authentication handling
  • 🌍 Support for all SettleMint environment variables
  • 📦 Version control for CLI installation
  • 🔌 Automatic workspace connection

Usage

Basic Example

steps:
  - uses: actions/checkout@v4
  - name: Run SettleMint CLI
    uses: settlemint/settlemint-action@main
    with:
      command: "workspace list"
      access-token: ${{ secrets.SETTLEMINT_ACCESS_TOKEN }}

Advanced Example

steps:
  - uses: actions/checkout@v4
  - name: Deploy Smart Contract
    uses: settlemint/settlemint-action@main
    with:
      command: "scs hardhat deploy remote --accept-defaults"
      access-token: ${{ secrets.SETTLEMINT_ACCESS_TOKEN }}
      version: "1.0.0"
      workspace: "my-workspace-ae70"
      blockchain-node: "my-node-3b8e"
      auto-connect: "true"

Inputs

Required

Input Description Required
access-token SettleMint Access Token (can be a personal or an application access token) Yes

Optional

Input Description Default
command CLI command to execute -
version CLI version to install 'latest'
auto-connect Automatically connect to workspace 'true' (only executed when access-token is a personal access token)
instance SettleMint instance URL 'https://console.settlemint.com'
workspace Workspace unique name -
application Application unique name -
blockchain-network Blockchain network unique name -
blockchain-node Blockchain node unique name -
load-balancer Load balancer unique name -
hasura Hasura unique name -
thegraph TheGraph unique name -
portal Portal unique name -
hd-private-key HD private key -
minio MinIO unique name -
ipfs IPFS unique name -
custom-deployment Custom deployment unique name -
blockscout Blockscout unique name -

Common Use Cases

Deploying Smart Contracts

- name: Deploy Contract
  uses: settlemint/settlemint-action@main
  with:
    command: scs hardhat deploy remote --accept-defaults
    access-token: ${{ secrets.SETTLEMINT_ACCESS_TOKEN }}
    workspace: ${{ vars.WORKSPACE_UNIQUE_NAME }}

Managing Workspaces

- name: List Workspaces
  uses: settlemint/settlemint-action@main
  with:
    command: workspace list
    access-token: ${{ secrets.SETTLEMINT_ACCESS_TOKEN }}

Custom Version Installation

- name: Use Specific CLI Version
  uses: settlemint/settlemint-action@main
  with:
    command: --version
    version: "1.0.0"
    access-token: ${{ secrets.SETTLEMINT_ACCESS_TOKEN }}

Environment Variables

All inputs are automatically converted to environment variables with the SETTLEMINT_ prefix. For example:

  • workspace → SETTLEMINT_WORKSPACE
  • blockchain-network → SETTLEMINT_BLOCKCHAIN_NETWORK

Environment Files

The action supports loading environment variables from .env files. You can provide the content of your env files through the following inputs:

  • dotEnvFile: Content of your main .env file
  • dotEnvLocalFile: Content of your .env.local file

⚠️ Important: Always store env file contents in GitHub Secrets:

steps:
  - uses: settlemint/settlemint-action@main
    with:
      dotEnvFile: ${{ secrets.MY_ENV_FILE }}
      dotEnvLocalFile: ${{ secrets.MY_ENV_LOCAL }}
      access-token: ${{ secrets.SETTLEMINT_ACCESS_TOKEN }}

The action will process these files and add all variables to the GitHub Actions environment. It handles:

  • Comments (lines starting with #)
  • Empty lines
  • Quoted values
  • Values containing = signs
  • Trailing comments

Error Handling

The action will fail if:

  • Invalid access token is provided
  • Required inputs are missing
  • CLI command execution fails
  • Network connectivity issues occur

Security

  • Never commit your access token directly in workflows
  • Use GitHub Secrets for sensitive information
  • Consider using OIDC for token management in production

Security Best Practices

Handling Secrets 🔒

  • NEVER commit access tokens, private keys or any secrets directly in your workflow files or repository

  • ALWAYS use GitHub Secrets for sensitive information:

    # ✅ CORRECT - Using GitHub Secrets
access-token: ${{ secrets.SETTLEMINT_ACCESS_TOKEN }}

# ❌ WRONG - NEVER do this
access-token: "your-token-here"  # This is a security risk!

  • Use GitHub's OIDC (OpenID Connect) for token management in production environments

  • Regularly rotate your access tokens and secrets

  • Limit secret access to only the necessary workflows and repositories

Environment Variables

When using .env files:

steps:
  - uses: settlemint/settlemint-action@main
    with:
      dotEnvFile: ${{ secrets.ENV_FILE_CONTENT }} # Store as a secret!
      access-token: ${{ secrets.SETTLEMINT_ACCESS_TOKEN }}

Contributing

Contributions are welcome! Please read our Contributing Guide for details on our code of conduct and the process for submitting pull requests.

License

This project is licensed under the FSL-1.1-MIT License - see the LICENSE file for details.

Support