README.md

togomak

togomak is a declarative pipeline orchestration tool, powered by HashiCorp Configuration Language (HCL) built on top of Terraform's architecture and features. It supports modules, custom HCL expressions.

togomak {
  version = 2
}
stage "hello" {
  script = "echo hello world"
}

$ togomak
0000 • togomak (version=dev)
0000 • [stage.hello]  hello world
0000 • took 2ms

Contents

• Installation
• Getting Started
• Features
• Using modules
• Documentation (wip)
• Examples

Installation

Download a compatible binary for your operating system and architecture from Releases. The v2.x tag has the latest, bleeding edge features which are more relevant.

Or, using go:

go install github.com/srevinsaju/togomak/v2@latest

Building and installing from source

1. Clone the repository, https://github.com/srevinsaju/togomak

2. cd cmd/togomak
   go build .
   ./togomak

Docker containers

Consider using the ghcr.io/srevinsaju/togomak:v2alpine image. Other flavors are available are available here.

Getting Started

togomak {
  version = 2
}

locals {
  validate = toset(["vet", "fmt", "test"])
}

variable "service" {
  type = string
  description = "Name of the service"
}

stage "build" {
  depends_on = [stage.validate]
  script = "echo Running go build ... for ${var.service}"
  post_hook {
    stage {
      script = "echo send slack message, build completed for ${upper(var.service)} with status: ${this.status}"
    }
  }
}

stage "validate" {
  for_each = local.validate
  script = "echo Running go ${each.value} ... for ${var.service}"
}

Installation

Check out the releases page for the v2.0.0-alpha.* release binaries, and other pre-built packages for your desired platform.

Building from Source

cd cmd/togomak 
go build

Building using togomak (what!)

togomak

Features

In togomak, a stage is a single independent task, and a module is a group of stages. Here is a non-exhaustive list of features. See the work in progress documentation or examples for a list of examples. These examples also run as part of an integration test, using tests/togomak.hcl.

• Concurrency: All stages and modules run in parallel by default.
• Modular: Create reusable parts of your CI/CD pipeline and use them from git, https, s3 buckets or gcs buckets.

  # modules/togomak.hcl
  ...
  variable "name" {
    type = string
    description = "Name of person"
  }
  stage "hello" {
    script = "echo ${var.name}"
  }

  # togomak.hcl
  ...
  module {
    source = "./modules"
    name = "srev"
  }

• Conditional: Run stages or modules by specifying a HCL expression in if meta-arguments.

  stage "hello" {
    if = env("USER") == "builder"
    ...
  }

• Built on top of Terraform's Architecture: supports most of Terraform's functions, block types, language, syntax and expression, keeping it a low learning curve for new and experienced users alike. Supports many familiar features like
  • local.<name> and locals {}
  • var.<name> and variable {}
  • Functions like sum(), flatten(), toset(), upper(), fileset(), setunion() and so on
  • for_each to iterate over a local, var to perform a stage or a module over different configurations.
• Lifecycles and Rule Engine: Configure how your pipeline behaves when you type togomak deploy or togomak build, or when you would like to allow-list a specific stage with togomak deploy +stage.some_stage and block a specific stage with togomak build ^stage.slack_hook. See Usage on how togomak uses them.

  ❯ togomak
  0000 • togomak (version=dev)
  0000 • [stage.alice]
  0000 • [stage.bob]  skipped
  0000 • [stage.eve]
  0000 • [stage.eve]  hello im default
  0000 • [stage.alice]  hello im default, deploy
  0000 • took 2ms
  ❯ togomak deploy
  0000 • togomak (version=dev)
  0000 • [stage.alice]
  0000 • [stage.bob]
  0000 • [stage.eve]  skipped
  0000 • [stage.bob]  hello im deploy
  0000 • [stage.alice]  hello im default, deploy
  0000 • took 2ms
  ❯ togomak all
  0000 • togomak (version=dev)
  0000 • [stage.bob]
  0000 • [stage.eve]
  0000 • [stage.alice]
  0000 • [stage.eve]  hello im default
  0000 • [stage.alice]  hello im default, deploy
  0000 • [stage.bob]  hello im deploy
  0000 • took 2ms
  

• Pre and Post Hooks: Runs commands or modules before and after the execution of a stage as well as an entire pipeline.
• Query Engine: Pass custom hcl expressions to togomak to choose which stages can run, and which cannot using the --query parameter on the command line.
• Comprehensive terraform-like error diagnostics with references to contents of the file where the error originates from.
• Terraform Support: Use terraform data blocks (or resource) blocks as data sources in your CI/CD pipeline. See examples/terraform for an example.

And don't forget to format your CICD files with togomak fmt.

Contributing

Contributions are welcome, and encouraged. Please check out the contributing guide for more information.

License

togomak is licensed under the MPL License v2.0