proposal: Add Git Reference Environment Variables to Spindle Workflows #286

Spindle workflows currently do not expose git branch, tag, or commit information as environment variables to workflow steps. This makes it difficult for users to access this critical information when building, tagging, or deploying their applications.

While this information is available internally within the workflow trigger struct (tr.Push.Ref, tr.Push.NewSha, tr.PullRequest.SourceBranch, etc.), it is not passed to the execution environment where workflow steps run.

Motivation#

Users need access to git reference information for common CI/CD tasks:

• Docker image tagging: Tag images with branch names or version tags (e.g., myapp:main, myapp:v1.2.3)
• Environment-based deployments: Deploy to different environments based on branch (e.g., main → production, staging → staging environment)
• Release artifact creation: Include version information from git tags in build artifacts
• Conditional workflow logic: Execute different steps based on branch or tag patterns

Current Workaround#

Currently, users must resort to complex git commands to extract this information:

- name: Get tag for current commit
  command: |
    # Fetch tags (shallow clone doesn't include them by default)
    git fetch --tags
     # Find the tag that points to the current commit
    TAG=$(git tag --points-at HEAD | grep -E '^v[0-9]' | head -n1)
     if [ -z "$TAG" ]; then
      echo "Error: No version tag found for current commit"
      echo "Available tags:"
      git tag
      echo "Current commit:"
      git rev-parse HEAD
      exit 1
    fi
    echo "Building version: $TAG"
    echo "$TAG" > .version
     # Also get the commit hash for reference
    COMMIT_HASH=$(git rev-parse HEAD)
    echo "Commit: $COMMIT_HASH"

This approach has several problems:

• Requires additional git fetch --tags
• Complex error handling for missing tags
• Boilerplate code repeated across workflows
• Unreliable in shallow clone scenarios

Proposal#

Add environment variables that expose git reference information:

For pull request workflows, additional variables could be added:

• TANGLED_PR_SOURCE_BRANCH
• TANGLED_PR_TARGET_BRANCH
• TANGLED_PR_SOURCE_SHA

Implementation#

Currently data and variables are only implemented at the nixery engine level. But if the intent is to support more engine types, these variables should be defined on the Workflow struct. It may take some refactoring of how the nixery engine works in order to move things to be more generalized.