Usage

ℹ️

togomak v2 had a non-backward compatible change in how command line parameters are evaluated. If you are looking for v1.x usage spec, see Usage v1.x.

Togomak includes a query language and a rule engine to choose which stages are run.

By default, togomak runs all stages which evaluates their condition stage.*.if to true. By default, all stages evaluate their condition to true, unless explicitly specified.

To simply run all stages which meet the criteria, just do

togomak

If your togomak pipeline lives in a different directory, you could:

togomak -C path/to/different/dir

Running specific lifecycles

A lifecycle is a group of stages, that needs to be run together.

For example, if you need to run a specific build lifecycle, you can use

togomak build

You can also specify multiple lifecycles:

togomak build deploy test

The order of the lifecycle specification is irrelevant to togomak. Togomak internally evaluates a dependency tree based on actual dependencies.

By default, unless explicitly specified, togomak runs all stages, modules and macros which has the default lifecycle. If a lifecycle meta-argument has not been specified, it may assume the value of ["default"].

💡

Example

Consider the following togomak configuration

togomak {
  version = 2
}
 
stage "alice" {
  lifecycle {
    phase = ["default", "deploy"]
  }
  script = "echo hello im default, deploy"
}
 
stage "bob" {
  lifecycle {
    phase = ["deploy"]
  }
  script = "echo hello im deploy"
}
 
stage "eve" {
  lifecycle {
    phase = ["default"]
  }
  script = "echo hello im default"
}

In the above case, lets consider the following possibilities:

togomak - Just running togomak without any arguments, would produce the following outputs

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

It's worthy to note, stage.bob was skipped. Only stage.alice and stage.eve ran.

togomak default - Running togomak with the default lifecycle, would produce the same results as that of togomak

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

Same inference as the previous attempt, stage.bob was skipped.

togomak deploy - We are explicitly requesting only for stages with the deploy lifecycle

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

In this scenario, stage.eve was skipped, but both stage.alice and stage.bob ran.

togomak deploy default - Now, we are requesting both lifecycles default and deploy to be run.

0000 • togomak (version=dev)
0000 • stage.eve               hello im default
0000 • stage.bob               hello im deploy
0000 • stage.alice             hello im default, deploy
0000 • took 3ms

There you have it, all three, stage.alice, stage.bob and stage.eve ran together.

So, if a specific lifecycle is not part of the default lifecycle phase, you can explicitly call it along with default

togomak default deploy

The above will run all stages, macros and modules which has the lifecycle default, along with that stages, macros and modules which has the deploy lifecycle.

However, the following command:

togomak deploy

... will only run the stages, macros and modules which has the lifecycle deploy. Anything which belongs to the default group will not be run, furthermore, if a particular stage has both lifecycle phases deploy and default, that particular stage would be executed because it contains atleast deploy which was explicitly requested through command line arguments.

ℹ️

Even when explicitly invoked with lifecycles on togomak, the stage's if attribute has a higher precedence. If a stage, such as

stage "test" {
  lifecycle {
    phases = ["deploy"]
  }
  if = false
}

and when togomak deploy is executed, stage.test will not be executed because stage.test.if evaluated to false. However, you can force it, using togomak deploy +stage.test. The + operator, forces the stage to run regardless of whether the block has its if condition evaluated to false

Running specific stages

You can request to run specific stages using the stage. prefix. This is true for other blocks like macro. and module. as well. For example,

togomak stage.alice

would only run the specific stage with the id alice. Effectively, we call this block overriden.

You may choose to provide multiple stage names too

togomak stage.alice stage.bob stage.eve

A stage's if condition takes precendence over explicitly requested stages. You can force a certain stage to run using the + prefix operator.

💡

Example

Consider the following togomak configuration where github_hook has an if condition set to togomak.ci. togomak.ci is a variable which is true when togomak detects that its running on a CI environment.

Imagine you are a developer, working on this pipeline:

togomak {
  version = 2
}
 
stage "setup" {
  lifecycle {
    phase = ["default", "deploy"]
  }
  script = "echo im setting things up for you!"
}
 
stage "terraform" {
  depends_on = [stage.docker, stage.setup]
  lifecycle {
    phase = ["deploy"]
  }
  script = "echo terraform apply!"
}
 
stage "github_hook" {
  if = togomak.ci 
  lifecycle {
    phase = ["deploy"]
  }
  script = "echo curl webhook!"
}
 
stage "docker" {
  lifecycle {
    phase = ["default"]
  }
  script = "echo docker build!"
}

Say you have already done the stage.setup step multiple times and you don't want to execute it every time you run togomak deploy.

Running togomak deploy on this gives the following output:

0000 • togomak (version=dev)
0000 • stage.docker            skipped
0000 • stage.setup             im setting things up for you!
0000 • stage.github_hook       skipped
0000 • stage.terraform         terraform apply!
0000 • took 3ms

If you would like to skip, just the stage.setup from being executed, you could add it to the exclude list using the ^, or the negation prefix operator.

togomak deploy ^stage.setup

This command translates to: "Run everything which belongs to the deploy lifecycle, except the stage called setup"

0000 • togomak (version=dev)
0000 • stage.github_hook       skipped
0000 • stage.setup             overridden
0000 • stage.docker            skipped
0000 • stage.terraform         terraform apply!
0000 • took 2ms

From the above output, you would notice that the stage.setup was skipped.

Now, if you would like to test the stage.github_hook?

togomak deploy ^stage.setup +stage.github_hook

0000 • togomak (version=dev)
0000 • stage.github_hook       overridden
0000 • stage.setup             overridden
0000 • stage.docker            skipped
0000 • stage.github_hook       curl webhook!
0000 • stage.terraform         terraform apply!
0000 • took 3ms

Yes, the stage.github_hook was executed this time despite if = togomak.ci was set. This is because the + operator ignores the stage.*.if condition, which is also the same for the ^ operator.

Running all lifecycle phases

There is a magic lifecycle phase which expands to every lifecycle. That is all

togomak all

would run all lifecycles including default, however stage.*.if has higher precendence, so you would like to take care of that.

Command Line Usage Examples