MetalDeploy Action

A comprehensive GitHub Action for deploying applications to baremetal servers via SSH. This action supports three deployment modes: baremetal (direct to server), Docker, and Kubernetes.

Features

• 🔐 Secure SSH Authentication - Support for SSH keys or password authentication
• 🎯 Multiple Deployment Types - Choose between baremetal (default), Docker, or Kubernetes deployments
• 🐳 Docker Support - Automatic Docker and Docker Compose installation
• ☸️ Kubernetes Support - Automatic k3s, kubectl, and helm installation
• 🔧 Auto Dependency Installation - Installs git and other required tools
• 🏷️ Registry Support - Supports GHCR, Docker Hub, and AWS ECR
• 🌿 Branch Management - Automatic branch switching based on environment
• ⚡ Smart Defaults - Automatically uses current repository and GitHub actor for Git operations
• 📝 Environment File Generation - Automatically create .env files from GitHub secrets and variables
• 🔒 All-in-One Secret Support - Store multiple variables in single secrets with multiple formats (ENV, JSON, YAML)
• 🏗️ Flexible File Structures - Support single, flat, nested, auto, and custom file organization
• 📦 Artifact Copying - Efficiently copy local build artifacts (dist/, node_modules) to the server with auto-compression
• 🚀 Multi-Server Deployment - Deploy to multiple servers concurrently with smart variable distribution
• 🎛️ Priority System - Environment-specific secrets override base secrets automatically
• 🏗️ Jenkins Compatible - Fully compatible with Jenkins via pre-built GHCR image and Jenkinsfile

Quick Links

• Deployment Types - Baremetal, Docker, and Kubernetes details
• Git Authentication - Token, SSH, and No-Auth methods
• Environment File Generation - Dynamic .env creation from secrets
• Jenkins Integration - Using MetalDeploy outside of GitHub Actions
• Manual CLI Usage - Running MetalDeploy directly from your machine
• Installation & Requirements - What gets installed on your server

Default Values

MetalDeploy provides smart defaults to minimize configuration:

• git_url: Defaults to ${{ github.repositoryUrl }} - automatically uses the current repository
• git_user: Defaults to ${{ github.actor }} - automatically uses the GitHub user triggering the workflow
• deployment_type: Defaults to baremetal - direct server deployment without containers
• git_auth_method: Defaults to none - no authentication (for public repos)
• environment: Defaults to dev - development environment
• remote_user: Defaults to root - root user on remote server
• registry_type: Defaults to ghcr - GitHub Container Registry

Quick Start

For Local CLI Usage

Install MetalDeploy as a global command:

curl -sSL https://raw.githubusercontent.com/OpsGuild/MetalDeploy/main/scripts/install.sh | bash

Then use it anywhere:

metaldeploy --host 1.2.3.4 --user root --ssh-key ~/.ssh/id_rsa --type docker

For GitHub Actions

- name: Deploy with MetalDeploy
  uses: OpsGuild/MetalDeploy@v1
  env:
    # Set/Override specific variables
    ENV_APP_PORT: 9090
  with:
    git_auth_method: token
    git_token: ${{ secrets.GITHUB_TOKEN }}
    remote_host: ${{ secrets.REMOTE_HOST }}
    ssh_key: ${{ secrets.SSH_PRIVATE_KEY }}
    environment: prod
    # Pass all secrets in one go (Zero-Config)
    # environment: prod

Advanced Example with Docker

- name: Deploy with MetalDeploy
  uses: OpsGuild/MetalDeploy@v1
  with:
    remote_host: ${{ secrets.REMOTE_HOST }}
    ssh_key: ${{ secrets.SSH_PRIVATE_KEY }}
    deployment_type: docker
    environment: prod
    registry_type: dockerhub
    registry_username: ${{ secrets.DOCKERHUB_USERNAME }}
    registry_username: ${{ secrets.DOCKERHUB_USERNAME }}
    registry_password: ${{ secrets.DOCKERHUB_PASSWORD }}

### Copying Build Artifacts

Copy specific files or directories (like `node_modules` or `dist/`) to the server. The action automatically compresses them for fast transfer.

```yaml
- name: Deploy with Artifacts
  uses: OpsGuild/MetalDeploy@v1
  with:
    remote_host: ${{ secrets.REMOTE_HOST }}
    ssh_key: ${{ secrets.SSH_PRIVATE_KEY }}
    # Copy local 'dist' folder to remote '/app/dist'
    # Copy local 'package.json' to remote '/app/package.json'
    copy_artifacts: "dist/:dist, package.json:package.json"

Secure Secret Management

• Bulk Injection: Use ENV to securely tunnel your raw variable block to your server.
• Manual Overrides: Use the standard GitHub Action env: block to override secrets for specific steps.

- name: Deploy with Overrides
  uses: OpsGuild/MetalDeploy@v1
  env:
    ENV_APP_PORT: 3000 # This wins over repository secrets
  with:
    env_files_generate: true

Multi-Server Deployment

Deploy to multiple servers concurrently by providing comma-separated lists for host configuration. If variable lists are shorter than remote_host, values are reused/distributed smartly.

• remote_host: server1,server2,server3
• remote_user: user1,user2 (user1->server1, user2->server2, user2->server3)
• ssh_key: key1 (key1 used for all servers)

- name: Deploy to Cluster
  uses: OpsGuild/MetalDeploy@v1
  with:
    remote_host: "10.0.1.1, 10.0.1.2, 10.0.1.3"
    remote_user: "admin" # Used for all hosts
    ssh_key: ${{ secrets.CLUSTER_SSH_KEY }}
    deployment_type: docker
    environment: prod

### For Jenkins

```groovy
pipeline {
    agent { docker { image "ghcr.io/opsguild/metal-deploy:latest" } }
    stages {
        stage('Deploy') {
            steps {
                script {
                    def paramEnv = params.collect { k, v -> "${k}=\${v}" }
                    withEnv(paramEnv) { sh "python main.py" }
                }
            }
        }
    }
}

Inputs & Outputs

For a full list of inputs and outputs, please see the Action Metadata.

Documentation

Comprehensive documentation can be found in the docs/ directory:

• Deployment Types: Detailed information about each deployment strategy.
• Git Authentication: How to configure repository access.
• Environment File Generation: Securely manage your application settings.
• Jenkins Integration: How to use this action in a Jenkins pipeline.
• Manual CLI Usage: Guide for running the tool manually.
• Installation & Requirements: Details about server setup and dependencies.

Development & Testing

See tests/README.md for details on the test suite and local development.

License

MIT License - see LICENSE file for details

Support

For issues and feature requests, please open an issue on the GitHub repository.