GitHub Actions

Smurf provides an official composite GitHub Action that downloads and installs the CLI on ubuntu, macos, and windows runners.

Setup action

- name: Setup Smurf
  uses: clouddrove/[email protected]
  with:
    version: v1.1.9   # or "latest"

Inputs

Input	Description	Default
version	Smurf version to install (vX.Y.Z or latest)	latest

The action automatically detects the runner OS and architecture (amd64 / arm64), downloads the matching release tarball, and verifies the installation with smurf --version.

Docker workflow

Build and push an image to AWS ECR:

name: Build and Push

on:
  push:
    branches: [main]

jobs:
  docker:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v5

      - name: Setup Smurf
        uses: clouddrove/[email protected]
        with:
          version: v1.1.9

      - name: Configure AWS credentials
        uses: aws-actions/configure-aws-credentials@v4
        with:
          aws-access-key-id: ${{ secrets.AWS_ACCESS_KEY_ID }}
          aws-secret-access-key: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
          aws-region: us-east-1

      - name: Build and push to ECR
        run: smurf sdkr provision-ecr

With smurf.yaml in the repository, omit the image URL from the command — Smurf reads it from config.

Helm workflow

Lint, template, and deploy a Helm chart:

name: Helm Deploy

on:
  push:
    branches: [main]

jobs:
  helm:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v5

      - name: Setup Smurf
        uses: clouddrove/[email protected]
        with:
          version: v1.1.9

      - name: Lint
        run: smurf selm lint ./charts/my-app

      - name: Template
        run: smurf selm template my-app ./charts/my-app

      - name: Deploy
        run: |
          smurf selm upgrade my-app ./charts/my-app \
            --install --atomic --wait \
            -n production

Or use the combined provision command:

      - name: Helm provision
        run: smurf selm provision

Terraform workflow

name: Terraform

on:
  push:
    branches: [main]

jobs:
  terraform:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v5

      - name: Setup Smurf
        uses: clouddrove/[email protected]
        with:
          version: v1.1.9

      - name: Init and validate
        run: |
          smurf stf init --dir=./infra
          smurf stf validate --dir=./infra

      - name: Plan
        run: smurf stf plan --dir=./infra

      - name: Apply
        if: github.ref == 'refs/heads/main'
        run: smurf stf apply --dir=./infra --auto-approve

Full deploy pipeline

Combine Docker build, registry push, and Helm deploy with a single command:

name: Deploy

on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v5

      - name: Setup Smurf
        uses: clouddrove/[email protected]
        with:
          version: v1.1.9

      - name: Configure AWS credentials
        uses: aws-actions/configure-aws-credentials@v4
        with:
          aws-access-key-id: ${{ secrets.AWS_ACCESS_KEY_ID }}
          aws-secret-access-key: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
          aws-region: us-east-1

      - name: Deploy
        run: smurf deploy

Ensure smurf.yaml is committed with the correct registry and Helm settings. See Configuration.

Pinning versions

Always pin the action tag and version input in production workflows:

uses: clouddrove/[email protected]
with:
  version: v1.1.9

Using latest is convenient for development but may introduce breaking changes without notice.

Required secrets

Workflow	Secrets / env vars
ECR	AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_REGION
Docker Hub	DOCKER_USERNAME, DOCKER_PASSWORD
GHCR	GITHUB_TOKEN (automatic in GHA) or GITHUB_USERNAME + custom PAT
GCP	GOOGLE_APPLICATION_CREDENTIALS or Workload Identity
ACR	AZURE_CLIENT_ID, AZURE_CLIENT_SECRET, AZURE_TENANT_ID
Helm	Kubernetes credentials (e.g. KUBECONFIG or cloud-specific auth)
Terraform	Backend credentials (e.g. S3 + DynamoDB, Terraform Cloud token)

Shared workflows

CloudDrove also maintains github-shared-workflows with reusable workflow templates that integrate Smurf for Docker, Helm, and Terraform operations. Refer to that repository for organization-wide pipeline patterns.