Configuration

jarkdown uses environment variables for configuration. This keeps sensitive credentials out of your code and command history.

Required Environment Variables

These three variables must be set for jarkdown to work:

JIRA_DOMAIN

Your Atlassian instance domain, without the protocol:

JIRA_DOMAIN=yourcompany.atlassian.net

Note: Do not include https:// - just the domain name.

JIRA_EMAIL

The email address associated with your Atlassian account:

JIRA_EMAIL=your.email@company.com

This should be the email you use to log into Jira.

JIRA_API_TOKEN

Your Atlassian API token (not your password):

JIRA_API_TOKEN=ATATT3xFfGF0A1B2C3D4E5F6G7H8I9J0

Generate this from your Atlassian Account Settings.

Configuration Methods

Method 2: Shell Export

Export variables in your current shell session:

export JIRA_DOMAIN=yourcompany.atlassian.net
export JIRA_EMAIL=your.email@company.com
export JIRA_API_TOKEN=your_token_here

Benefits:

  • Quick for one-time use

  • No files to manage

Drawbacks:

  • Must re-export in each new terminal

  • Variables visible in shell history

Method 3: Shell Profile

Add exports to your shell profile for permanent configuration:

# ~/.bashrc, ~/.zshrc, or equivalent
export JIRA_DOMAIN=yourcompany.atlassian.net
export JIRA_EMAIL=your.email@company.com
export JIRA_API_TOKEN=your_token_here

Then reload your profile:

source ~/.bashrc  # or ~/.zshrc

Benefits:

  • Always available

  • Works across all projects

Drawbacks:

  • Credentials in your profile

  • Same credentials for all projects

Method 4: direnv (Advanced)

Use direnv for directory-specific environment:

# .envrc
export JIRA_DOMAIN=yourcompany.atlassian.net
export JIRA_EMAIL=your.email@company.com
export JIRA_API_TOKEN=your_token_here

Benefits:

  • Automatic loading when entering directory

  • Automatic unloading when leaving

  • Per-project configuration

Security Best Practices

Protecting Your Credentials

  1. Never commit credentials to Git

    • .env is in .gitignore

    • Don’t commit .envrc files

    • Review commits before pushing

  2. Use appropriate file permissions

    chmod 600 .env  # Only you can read/write

  3. Rotate tokens regularly

    • Delete old tokens from Atlassian

    • Generate new tokens periodically

    • Update your configuration

  4. Use separate tokens for different purposes

    • Development token

    • CI/CD token

    • Production token

Secure Storage Options

For enhanced security, consider:

  1. Operating System Keychains

    # macOS Keychain example
security add-generic-password -s "jarkdown" -a "api-token" -w "your_token"

  2. Password Managers

    • Store credentials in 1Password, LastPass, etc.

    • Copy to .env when needed

  3. Environment Management Tools

Validation and Testing

Check Your Configuration

Verify all variables are set:

# Check if variables are set
echo "JIRA_DOMAIN: ${JIRA_DOMAIN:=NOT SET}"
echo "JIRA_EMAIL: ${JIRA_EMAIL:=NOT SET}"
echo "JIRA_API_TOKEN: ${JIRA_API_TOKEN:=NOT SET}"

Test Connection

Test with a known accessible issue:

jarkdown PROJ-1 --verbose

Common Configuration Issues

Issue: “JIRA_DOMAIN not found”

Solution: Ensure the variable is exported:

export JIRA_DOMAIN=yourcompany.atlassian.net

Issue: “401 Unauthorized”

Causes and solutions:

  • Wrong email: Verify JIRA_EMAIL matches your account

  • Wrong token: Regenerate token in Atlassian settings

  • Token expired: Create a new token

Issue: “Connection refused”

Check:

  • Domain doesn’t include https://

  • Domain spelling is correct

  • Your network allows HTTPS connections

Advanced Configuration

Using Different Configurations

For multiple Jira instances:

# Create multiple .env files
.env.prod    # Production Jira
.env.dev     # Development Jira
.env.client  # Client's Jira

# Switch between them
cp .env.prod .env
jarkdown PROD-123

cp .env.dev .env
jarkdown DEV-456

Configuration in CI/CD

For GitHub Actions:

- name: Export Jira Issue
  env:
    JIRA_DOMAIN: ${{ secrets.JIRA_DOMAIN }}
    JIRA_EMAIL: ${{ secrets.JIRA_EMAIL }}
    JIRA_API_TOKEN: ${{ secrets.JIRA_API_TOKEN }}
  run: |
    pip install jarkdown
    jarkdown PROJ-123

Proxy Configuration

If behind a corporate proxy:

# Set proxy for Python requests
export HTTP_PROXY=http://proxy.company.com:8080
export HTTPS_PROXY=http://proxy.company.com:8080

# Run jarkdown
jarkdown PROJ-123

Troubleshooting Configuration

Debug Mode

See exactly what’s being sent:

# Enable debug logging (if implemented)
export JIRA_DEBUG=true
jarkdown PROJ-123 --verbose

Reset Configuration

Start fresh if having issues:

# Clear environment variables
unset JIRA_DOMAIN JIRA_EMAIL JIRA_API_TOKEN

# Remove .env file
rm .env

# Start over with configuration

Next Steps