MCUXpresso SDK Documentation
Open on Repo Open an Issue
Source (.md/.rst) Page PDF (.pdf)

Environment Variables

Environment Variables#

This document describes the environment variables required for running release management and CI/CD scripts in the Bifrost SDK project.

Overview#

For security reasons, credentials and tokens are not stored in version control. Instead, they must be provided via environment variables. This document lists all required environment variables and provides setup instructions.

Required Environment Variables#

Bitbucket API Access#

ATLASSIAN_USERNAME#

  • Used by: scripts/mcux_pr/* (all west pr* commands)

  • Purpose: Shared Atlassian account username for Bitbucket (and potentially other Atlassian services)

  • Note: Preferred over USERNAME in CI because USERNAME is commonly pre-set by the OS on Windows.

ATLASSIAN_PASSWORD#

  • Used by: scripts/mcux_pr/* (all west pr* commands)

  • Purpose: Shared Atlassian account password for Bitbucket (and potentially other Atlassian services)

  • Note: Prefer token-based auth (BITBUCKET_TOKEN) when possible.

ATLASSIAN_DISPLAYNAME#

  • Used by: scripts/mcux_pr/* (all west pr* commands)

  • Purpose: Git committer display name used by CI/service-account workflows (when CLI --gituser is not provided)

ATLASSIAN_EMAIL#

  • Used by: scripts/mcux_pr/* (all west pr* commands)

  • Purpose: Git committer email used by CI/service-account workflows (when CLI --gitemail is not provided)

BITBUCKET_TOKEN#

  • Used by:

  • Purpose: Authentication token for creating release branches via Bitbucket API

  • How to obtain: Generate a personal access token from Bitbucket settings with repository write permissions

  • Required permissions: Repository write, pull request read/write

BITBUCKET_USERNAME#

BITBUCKET_PASSWORD#

  • Used by:

  • Purpose: Password for Bitbucket API authentication when parsing PR changes

  • How to obtain: Your Bitbucket account password or app-specific password

  • Note: Consider using app-specific passwords instead of your main account password

GitHub API Access#

GITHUB_TOKEN#

  • Used by: scripts/west_commands/release_syncgithub.py

  • Purpose: Personal access token for synchronizing releases to GitHub

  • How to obtain: Generate a personal access token from GitHub settings → Developer settings → Personal access tokens

  • Required permissions: repo (full control of private repositories)

GITHUB_BOT_ACCOUNT (Optional)#

MCUX Business Intelligence#

MCUX_BI_USERNAME#

MCUX_BI_PASSWORD#

MCUX_BI_EMAIL (Optional)#

Setup Instructions#

Windows Command Prompt (cmd.exe)#

Set environment variables for the current session:

set BITBUCKET_TOKEN=your_token_here
set BITBUCKET_USERNAME=your_username
set BITBUCKET_PASSWORD=your_password
set GITHUB_TOKEN=your_github_token
set GITHUB_BOT_ACCOUNT=McuxCIBot
set MCUX_BI_USERNAME=your_bi_username
set MCUX_BI_PASSWORD=your_bi_password
set MCUX_BI_EMAIL=your_email@example.com

To set permanently (system-wide):

setx BITBUCKET_TOKEN "your_token_here"
setx GITHUB_TOKEN "your_github_token"

Note: setx requires reopening the terminal to take effect.

Windows PowerShell#

Set environment variables for the current session:

$env:BITBUCKET_TOKEN = 'your_token_here'
$env:BITBUCKET_USERNAME = 'your_username'
$env:BITBUCKET_PASSWORD = 'your_password'
$env:GITHUB_TOKEN = 'your_github_token'
$env:GITHUB_BOT_ACCOUNT = 'McuxCIBot'
$env:MCUX_BI_USERNAME = 'your_bi_username'
$env:MCUX_BI_PASSWORD = 'your_bi_password'
$env:MCUX_BI_EMAIL = 'your_email@example.com'

To set permanently (user profile):

[System.Environment]::SetEnvironmentVariable('BITBUCKET_TOKEN', 'your_token_here', 'User')
[System.Environment]::SetEnvironmentVariable('GITHUB_TOKEN', 'your_github_token', 'User')

Unix/Linux/macOS (bash/zsh)#

Set environment variables for the current session:

export BITBUCKET_TOKEN=your_token_here
export BITBUCKET_USERNAME=your_username
export BITBUCKET_PASSWORD=your_password
export GITHUB_TOKEN=your_github_token
export GITHUB_BOT_ACCOUNT=McuxCIBot
export MCUX_BI_USERNAME=your_bi_username
export MCUX_BI_PASSWORD=your_bi_password
export MCUX_BI_EMAIL=your_email@example.com

To set permanently, add the above lines to your shell profile:

# For bash
echo 'export BITBUCKET_TOKEN=your_token_here' >> ~/.bashrc
echo 'export GITHUB_TOKEN=your_github_token' >> ~/.bashrc

# For zsh
echo 'export BITBUCKET_TOKEN=your_token_here' >> ~/.zshrc
echo 'export GITHUB_TOKEN=your_github_token' >> ~/.zshrc

Then reload your profile:

source ~/.bashrc  # or ~/.zshrc

CI/CD Environment Setup#

GitHub Actions#

Add secrets to your repository (Settings → Secrets and variables → Actions):

- name: Run release script
  env:
    BITBUCKET_TOKEN: ${{ secrets.BITBUCKET_TOKEN }}
    GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
    MCUX_BI_USERNAME: ${{ secrets.MCUX_BI_USERNAME }}
    MCUX_BI_PASSWORD: ${{ secrets.MCUX_BI_PASSWORD }}
  run: west release-createbranch

Jenkins#

Configure credentials in Jenkins (Manage Jenkins → Credentials) and use them in your pipeline:

withCredentials([
    string(credentialsId: 'bitbucket-token', variable: 'BITBUCKET_TOKEN'),
    string(credentialsId: 'github-token', variable: 'GITHUB_TOKEN'),
    usernamePassword(credentialsId: 'mcux-bi-creds',
                     usernameVariable: 'MCUX_BI_USERNAME',
                     passwordVariable: 'MCUX_BI_PASSWORD')
]) {
    sh 'west release-createbranch'
}

GitLab CI/CD#

Add variables to your project (Settings → CI/CD → Variables):

release:
  script:
    - west release-createbranch
  variables:
    BITBUCKET_TOKEN: $BITBUCKET_TOKEN
    GITHUB_TOKEN: $GITHUB_TOKEN
    MCUX_BI_USERNAME: $MCUX_BI_USERNAME
    MCUX_BI_PASSWORD: $MCUX_BI_PASSWORD

Security Best Practices#

  1. Never commit credentials to version control

    • Always use environment variables or secure credential storage

    • Review commits before pushing to ensure no credentials are included

  2. Use app-specific passwords when possible

    • Generate dedicated tokens/passwords for CI/CD instead of using main account credentials

    • This limits the impact if credentials are compromised

  3. Rotate credentials regularly

    • Update tokens and passwords on a regular schedule

    • Immediately rotate if you suspect credentials have been compromised

  4. Use minimal required permissions

    • Grant only the permissions needed for the specific task

    • For example, use read-only tokens where write access is not needed

  5. Secure credential storage in CI/CD

    • Use your CI/CD platform’s secure secret storage features

    • Never expose secrets in logs or output

  6. Use .gitignore for local credential files

    • The .env file is already in .gitignore to prevent accidental commits

    • Never commit your .env file to version control

    • See .env.example for a template

  7. Install python-dotenv dependency

    • Required for automatic .env file loading: pip install python-dotenv

    • Without this package, you must set environment variables manually

Troubleshooting#

Error: “Bitbucket token not found”#

Cause: The BITBUCKET_TOKEN environment variable is not set.

Solution:

# Windows cmd
set BITBUCKET_TOKEN=your_token_here

# Windows PowerShell
$env:BITBUCKET_TOKEN = 'your_token_here'

# Unix/Linux/macOS
export BITBUCKET_TOKEN=your_token_here

Error: “GitHub token not found”#

Cause: The GITHUB_TOKEN environment variable is not set.

Solution:

# Windows cmd
set GITHUB_TOKEN=your_github_token

# Windows PowerShell
$env:GITHUB_TOKEN = 'your_github_token'

# Unix/Linux/macOS
export GITHUB_TOKEN=your_github_token

Error: “MCUX BI credentials not found”#

Cause: Either MCUX_BI_USERNAME or MCUX_BI_PASSWORD (or both) are not set.

Solution:

# Windows cmd
set MCUX_BI_USERNAME=your_username
set MCUX_BI_PASSWORD=your_password

# Windows PowerShell
$env:MCUX_BI_USERNAME = 'your_username'
$env:MCUX_BI_PASSWORD = 'your_password'

# Unix/Linux/macOS
export MCUX_BI_USERNAME=your_username
export MCUX_BI_PASSWORD=your_password

Environment variables not persisting#

Windows: Use setx instead of set, or set them in System Properties → Environment Variables.

Unix/Linux/macOS: Add the export commands to your shell profile (~/.bashrc, ~/.zshrc, etc.) and reload it.

CI/CD pipeline fails with authentication errors#

Solution:

  1. Verify that secrets are correctly configured in your CI/CD platform

  2. Check that variable names match exactly (case-sensitive)

  3. Ensure tokens have the required permissions

  4. Check token expiration dates and rotate if needed

Additional Resources#

Support#

For issues or questions about environment variables and credentials:

  1. Check this documentation first

  2. Review the error messages for specific guidance

  3. Contact your team’s DevOps or security administrator

  4. Refer to the project’s main readme.md for general setup instructions

Contents