Named Values

Phobos lets you reference various values throughout your pipeline templates using named value expressions. Think of these as shortcuts to access information about your pipeline, variables, tokens, and task outputs while your pipeline is running.

What are Named Values?

Named values are expressions that give you access to data within your pipeline. You can use them anywhere in your HCL configuration where you need to reference dynamic information—like checking if a task succeeded, accessing a variable, or using an output from a previous task.

Types of Named Values

Phobos provides several categories of named values:

• var - Access variables defined in your pipeline
• jwt - Reference JWT tokens for authentication
• vcs_token - Access version control system tokens
• pipeline - Reference pipeline attributes, stage status, task outputs, and more
• this - Access data from within the current task context
• action_outputs - Access action output values (deprecated)
• phobos - Access phobos context variables (deprecated)

Variables

var.<NAME> gives you access to variables defined in your pipeline configuration.

Variables let you parameterize your pipelines so you can reuse the same template with different values. When you reference a variable using var.<NAME>, you get the value that was provided when the pipeline was created.

variable "app_version" {
  type = string
}

stage "build" {
  task "compile" {
    action "exec_command" {
      command = <<EOF
        echo "Building version ${var.app_version}"
      EOF
    }
  }
}

JWT Tokens

jwt.<NAME> provides access to JWT tokens that can be used for authentication with external services.

Use JWT tokens when your pipeline needs to authenticate with APIs or services that require token-based authentication.

jwt "api_token" {
  audience = "my-api"
}

stage "deploy" {
  task "authenticate" {
    action "exec_command" {
      command = <<EOF
        curl -H "Authorization: Bearer ${jwt.api_token}" https://api.example.com/deploy
      EOF
    }
  }
}

VCS Tokens

vcs_token.<NAME> gives you access to version control system tokens for interacting with your repository.

These tokens are useful when your pipeline needs to clone repositories, push changes, or interact with your VCS provider's API.

vcs_token "github" {
  provider_id = "prn:vcs_provider:org-name/provider-name"
}

stage "checkout" {
  task "clone_repo" {
    action "exec_command" {
      command = <<EOF
        git clone https://${vcs_token.github.value}@github.com/org/repo.git
      EOF
    }
  }
}

Pipeline Named Values

The pipeline namespace is the most powerful set of named values in Phobos. It gives you access to information about your pipeline's structure, execution state, and outputs.

Pipeline Attributes

Access top-level information about your pipeline:

• pipeline.id - The unique identifier for this pipeline run
• pipeline.project.name - The name of the project this pipeline belongs to
• pipeline.template.name - The name of the template being used
• pipeline.template.version - The version of the template being used
• pipeline.environment.name - The environment this pipeline is running in

stage "notify" {
  task "send_notification" {
    action "exec_command" {
      command = <<EOF
        echo "Pipeline ${pipeline.id} is running in ${pipeline.environment.name}"
        echo "Using template ${pipeline.template.name} version ${pipeline.template.version}"
      EOF
    }
  }
}

Stage and Task Status

Check the execution status of stages and tasks to make decisions in your pipeline:

• pipeline.stage.<STAGE_NAME>.status - The status of a specific stage
• pipeline.stage.<STAGE_NAME>.task.<TASK_NAME>.status - The status of a specific task

Status values include SUCCEEDED, FAILED, RUNNING, and others. This is particularly useful for conditional execution.

stage "build" {
  task "compile" {
    on_error = "continue"
    action "exec_command" {
      command = "make build"
    }
  }
}

stage "test" {
  task "run_tests" {
    # Only run if the compile task succeeded
    if = pipeline.stage.build.task.compile.status == "SUCCEEDED"

    action "exec_command" {
      command = "make test"
    }
  }

  task "notify_failure" {
    # Only run if the build failed
    if = pipeline.stage.build.task.compile.status == "FAILED"

    action "exec_command" {
      command = <<EOF
        echo "Build failed, skipping tests"
      EOF
    }
  }
}

Task Outputs

Access outputs from previous tasks to pass data through your pipeline:

• pipeline.stage.<STAGE_NAME>.task.<TASK_NAME>.outputs.<OUTPUT_NAME> - Access a specific output from a task

Outputs let you share data between tasks, like passing build artifacts, version numbers, or computed values.

stage "build" {
  task "compile" {
    action "exec_command" {
      command = "make build"
    }

    output "build_number" {
      value = "1.2.3"
    }
  }
}

stage "deploy" {
  task "upload" {
    action "exec_command" {
      command = <<EOF
        echo "Deploying build ${pipeline.stage.build.task.compile.outputs.build_number}"
      EOF
    }
  }
}

Nested Pipeline Outputs

Access outputs from nested pipelines that are invoked within a stage:

• pipeline.stage.<STAGE_NAME>.pipeline.<PIPELINE_NAME>.outputs.<OUTPUT_NAME> - Access outputs from a nested pipeline

stage "orchestration" {
  pipeline "child_pipeline" {
    # Configuration for nested pipeline
  }

  task "use_child_output" {
    dependencies = ["child_pipeline"]

    action "exec_command" {
      command = <<EOF
        echo "Child pipeline result: ${pipeline.stage.orchestration.pipeline.child_pipeline.outputs.result}"
      EOF
    }
  }
}

The this Context

When you're inside a task, the this keyword gives you access to information about the current task without needing to specify the full pipeline path.

Action Outputs

Access outputs from actions within the current task:

• this.action.<ACTION_NAME>.outputs.<OUTPUT_NAME> - Access an output from a specific action in this task

This is especially useful when you have multiple actions in a task and need to use the result of one action in another part of the task.

stage "process" {
  task "run_script" {
    action "exec_command" {
      command = <<EOF
        ./my-script.sh
        exit 0
      EOF
    }

    output "status_message" {
      value = "Script completed with exit code ${this.action.exec_command.outputs.exit_code}"
    }
  }
}

Current Task Attempt Count

Access the attempt count for the current task:

• this.attempt_count - The number of times the current task has been attempted

stage "retry_example" {
  task "flaky_task" {
    action "exec_command" {
      command = <<EOF
        echo "This is attempt number ${this.attempt_count}"
        # Your command here
      EOF
    }
  }
}

Complete Example

Here's a complete pipeline template that demonstrates various named values working together:

variable "app_name" {
  type = string
}

variable "version" {
  type = string
}

plugin exec {}

stage "build" {
  task "compile" {
    on_error = "continue"

    action "exec_command" {
      command = <<EOF
        echo "Building ${var.app_name} version ${var.version}"
        echo "Attempt: ${this.attempt_count}"
        make build
      EOF
    }

    output "timestamp" {
      value = timestamp()
    }

    output "build_status" {
      value = "Completed with exit code ${this.action.exec_command.outputs.exit_code}"
    }
  }

  task "handle_failure" {
    dependencies = ["compile"]
    if = pipeline.stage.build.task.compile.status == "FAILED"

    action "exec_command" {
      command = <<EOF
        echo "Build failed"
      EOF
    }
  }

  task "handle_success" {
    dependencies = ["compile"]
    if = pipeline.stage.build.task.compile.status == "SUCCEEDED"

    action "exec_command" {
      command = <<EOF
        echo "Build succeeded!"
        echo "Proceeding with deployment"
      EOF
    }

    output "message" {
      description = "Success message with build details"
      value = "Build completed at ${pipeline.stage.build.task.compile.outputs.timestamp} - ${pipeline.stage.build.task.compile.outputs.build_status}"
    }
  }
}

stage "deploy" {
  task "deploy_app" {
    action "exec_command" {
      command = <<EOF
        echo "Deploying to ${pipeline.environment.name}"
        echo "Build info: ${pipeline.stage.build.task.handle_success.outputs.message}"
        # Deployment commands here
      EOF
    }
  }
}

output "pipeline_summary" {
  value = "Pipeline ${pipeline.id} completed in ${pipeline.environment.name}"
}

Deprecated Named Values

warning

The action_outputs and phobos named values are deprecated and will be removed in a future version. Use the new syntax documented above instead.

action_outputs (Deprecated)

The action_outputs syntax was previously used to access action outputs from other tasks. This has been replaced by task outputs which can be referenced using the task path or the this context if the action is within the same task it's being referenced in.

Old syntax (deprecated):

stage "build" {
  task "compile" {
    action "exec_command" {
      command = "make build"
    }
  }

  task "deploy" {
    action "exec_command" {
      command = <<EOF
        echo "Exit code: ${action_outputs.stage.build.task.compile.action.exec_command.exit_code}"
      EOF
    }
  }
}

New syntax:

stage "build" {
  task "compile" {
    action "exec_command" {
      command = "make build"
    }
    output "exit_code" {
      value = this.action.exec_command.outputs.exit_code
    }
  }

  task "deploy" {
    action "exec_command" {
      command = <<EOF
        echo "Exit code: ${pipeline.stage.build.task.compile.outputs.exit_code}"
      EOF
    }
  }
}

phobos (Deprecated)

The phobos namespace was previously used to access pipeline-level information. This has been replaced by the pipeline namespace.

Old syntax (deprecated):

action "exec_command" {
  command = <<EOF
    echo "Organization: ${phobos.organization.name}"
    echo "Project: ${phobos.project.name}"
    echo "Environment: ${phobos.environment.name}"
    echo "Template: ${phobos.template.name} v${phobos.template.version}"
  EOF
}

New syntax:

action "exec_command" {
  command = <<EOF
    echo "Organization: ${pipeline.organization.name}"
    echo "Project: ${pipeline.project.name}"
    echo "Environment: ${pipeline.environment.name}"
    echo "Template: ${pipeline.template.name} v${pipeline.template.version}"
  EOF
}

Key Concepts

Dependencies and Execution Order

Named values respect task dependencies. You can only reference outputs from tasks that have already completed. Use the dependencies attribute to ensure tasks run in the correct order.

Conditional Execution

Use named values in if conditions to control whether tasks run based on the status or outputs of previous tasks. This is powerful for error handling and branching logic.

Data Flow

Outputs are the primary way to pass data between tasks. Define outputs in one task and reference them in subsequent tasks using the pipeline.stage.<STAGE>.task.<TASK>.outputs.<OUTPUT> pattern.

Context Awareness

The this keyword is only available within task blocks. Use it to keep your configuration cleaner when referencing data from the current task. For cross-task references, use the full pipeline path.