Bamboo Variable Hierarchy: Preventing Configuration Drift in CI/CD Pipelines

The biggest risk in Bamboo CI/CD pipelines is configuration drift—when environment-specific values like API endpoints or credentials accidentally leak into scripts because they're hardcoded. This breaks the ability to promote the same artifact through dev, staging, and production. The solution is leveraging Bamboo's variable hierarchy correctly, where more specific definitions override broader ones.

How Bamboo Resolves Variables

Bamboo uses a strict precedence order. When the same variable name exists at multiple levels, the most specific wins:

• Job Variables: Highest precedence—specific to a single job
• Plan Variables: Defined at the plan level
• Project Variables: Broadest scope—shared across all plans in a project
• Plan Parameters: Runtime values injected during manual triggers

This means a job-level variable named api_url will mask a plan-level variable of the same name.

Practical Example: Secure Multi-Environment Deployment

Configure a deployment job that uses different API endpoints based on environment selection:

Step 1: Create a Plan Parameter

Navigate to Plan Configuration > Parameters. Add:

• Name: target_env
• Type: Text
• Default: dev

This lets users specify the environment when triggering a build manually.

Step 2: Define Secret Variables

Go to Variables tab and add:

• Name: deploy_token
• Type: Secret

Secret variables mask their values with asterisks in logs, preventing credential exposure.

Step 3: Use Variables in Script

Access variables using the ${bamboo.variable} syntax in a script step:

#!/bin/bash
# Environment selection via plan parameter
ENV="${bamboo.target_env}"

# Secure credential via secret variable
TOKEN="${bamboo.deploy_token}"

echo "Deploying to: $ENV"

# Environment-specific logic
if [ "$ENV" = "prod" ]; then
    API_URL="https://api.production.example.com"
else
    API_URL="https://api.staging.example.com"
fi

curl -X POST \
    -H "Authorization: Bearer $TOKEN" \
    -d "build=${bamboo.buildNumber}" \
    "$API_URL/deploy"

Verification Checklist

Run these checks to confirm your configuration works:

1. Resolution Test: Add a script step with echo "Environment: ${bamboo.target_env}". Verify output matches your manual input.
2. Masking Test: Add echo "Token: ${bamboo.deploy_token}". Confirm logs show **** not the actual token.
3. Override Test: Trigger a build manually with target_env=prod. Ensure the script uses the production URL.

Common Pitfalls to Avoid

• Naming Conflicts: Using the same variable name at multiple levels causes unexpected overrides. Use descriptive names like api_url_dev and api_url_prod.
• Plain Text Secrets: Never store credentials in regular variables. Always use Secret type to prevent log exposure.
• Global Overuse: Defining everything at the plan level creates maintenance nightmares. Use job-level variables for environment-specific values.
• Hardcoded Values: Even "temporary" hardcoded URLs will eventually cause deployment failures in other environments.

Limitations

Bamboo variables have specific constraints:

• Variable names cannot contain spaces or special characters
• Secret values cannot be retrieved by other variables (no variable interpolation for secrets)
• Plan parameters require manual triggering or API calls—they don't auto-populate

To verify your setup works correctly, run a build with echo ${bamboo.target_env} and confirm the output matches your input. If you see the literal string ${bamboo.target_env}, the variable wasn't resolved—check that you're using the correct syntax and that the variable exists at the appropriate scope.