https://github.com/opsguild/metaldeploy
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.
https://github.com/opsguild/metaldeploy
bare-metal ci-cd deploy devops docker infra kubernetes pipeline workflow
Last synced: 2 months ago
JSON representation
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.
- Host: GitHub
- URL: https://github.com/opsguild/metaldeploy
- Owner: OpsGuild
- License: mit
- Created: 2025-11-06T11:19:55.000Z (5 months ago)
- Default Branch: main
- Last Pushed: 2026-01-28T21:08:39.000Z (2 months ago)
- Last Synced: 2026-01-28T23:25:45.426Z (2 months ago)
- Topics: bare-metal, ci-cd, deploy, devops, docker, infra, kubernetes, pipeline, workflow
- Language: Python
- Homepage: https://github.com/marketplace/actions/baremetal-pipeline
- Size: 181 KB
- Stars: 3
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: changelogs/2026-01-28_08-11-32.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
Awesome Lists containing this project
README
# 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](docs/deployment-types.md) - Baremetal, Docker, and Kubernetes details
- [Git Authentication](docs/git-auth.md) - Token, SSH, and No-Auth methods
- [Environment File Generation](docs/env-generation.md) - Dynamic `.env` creation from secrets
- [Jenkins Integration](docs/jenkins.md) - Using MetalDeploy outside of GitHub Actions
- [Manual CLI Usage](docs/manual-usage.md) - Running MetalDeploy directly from your machine
- [Installation & Requirements](docs/installation.md) - 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:
```bash
curl -sSL https://raw.githubusercontent.com/OpsGuild/MetalDeploy/main/scripts/install.sh | bash
```
Then use it anywhere:
```bash
metaldeploy --host 1.2.3.4 --user root --ssh-key ~/.ssh/id_rsa --type docker
```
### For GitHub Actions
```yaml
- 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
```yaml
- 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.
```yaml
- 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)
```yaml
- 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](action.yml).
## Documentation
Comprehensive documentation can be found in the [docs/](docs/) directory:
- [Deployment Types](docs/deployment-types.md): Detailed information about each deployment strategy.
- [Git Authentication](docs/git-auth.md): How to configure repository access.
- [Environment File Generation](docs/env-generation.md): Securely manage your application settings.
- [Jenkins Integration](docs/jenkins.md): How to use this action in a Jenkins pipeline.
- [Manual CLI Usage](docs/manual-usage.md): Guide for running the tool manually.
- [Installation & Requirements](docs/installation.md): Details about server setup and dependencies.
## Development & Testing
See [tests/README.md](tests/README.md) for details on the test suite and local development.
## License
MIT License - see [LICENSE](LICENSE) file for details
## Support
For issues and feature requests, please open an issue on the [GitHub repository](https://github.com/OpsGuild/MetalDeploy).