API Token Setup Guide

This guide explains how to configure API tokens for the JIRA automation pipeline using Bitbucket Repository Variables.

🚀 Bitbucket Repository Variables Setup

1. Access Repository Variables

1. Go to your Bitbucket repository
2. Click Repository settings (gear icon)
3. Under PIPELINES, click Repository variables

2. Get Required API Tokens

JIRA API Token

1. Go to Atlassian Account Settings
2. Click Create API token
3. Enter a label (e.g., "Documentation Automation")
4. Copy the generated token

Anthropic API Key

1. Go to Anthropic Console
2. Navigate to API Keys
3. Click Create Key
4. Copy the key (starts with sk-ant-api03-)

Note: Claude Code CLI requires an API key for authentication in pipeline environments.

Bitbucket Access Token

1. Go to Bitbucket Settings → Personal Bitbucket settings
2. Click App passwords
3. Click Create app password
4. Select permissions:
   • Repositories: Read, Write
   • Pull requests: Read, Write
   • Issues: Read (optional)
5. Copy the generated password

3. Configure Repository Variables

Add these variables in Bitbucket Repository Variables:

Variable Name	Type	Value	Description
JIRA_URL	Regular	https://superna.atlassian.net	Your Atlassian instance URL
JIRA_EMAIL	Regular	your-email@superna.com	Your Superna email address
JIRA_API_TOKEN	Secured	ATATT3xFfGF0...	Your JIRA API token
ANTHROPIC_API_KEY	Secured	sk-ant-api03-...	Your Anthropic API key
BITBUCKET_TOKEN	Secured	your-app-password	Bitbucket app password
BITBUCKET_WORKSPACE	Regular	superna	Bitbucket workspace
BITBUCKET_REPO_SLUG	Regular	public-documentation	Repository name
DEFAULT_REVIEWERS	Regular	john.doe,jane.smith	Default PR reviewers (optional)

Important: Mark sensitive tokens as Secured to encrypt them.

4. Firebase Variables (Already Configured)

These should already exist for your Firebase deployment:

• FIREBASE_SERVICE_ACCOUNT_ENCODED (Secured)

🔧 Pipeline Integration

The pipeline will automatically use these variables when running the auto-documentation scripts. No additional configuration needed.

Auto-Doc Branch Workflow

1. JIRA automation creates branch auto-doc/ISSUE-KEY
2. Pipeline triggers automatically
3. Scripts access Repository Variables
4. Documentation generated and PR created
5. JIRA updated with results

🧪 Testing

The pipeline includes environment validation:

• All required variables are checked
• API connections are tested
• Clear error messages if anything is missing

🔒 Security Best Practices

• ✅ Use Secured variables for all API tokens
• ✅ Limit API token permissions to minimum required
• ✅ Use service accounts where possible
• ✅ Regularly rotate API tokens
• ✅ Monitor API token usage

🔧 Troubleshooting

Common Issues

"Authentication failed"

• Verify your email and API token are correct in Repository Variables
• Check if API token has expired
• Ensure you're using the correct JIRA URL

"Pipeline fails during Claude Code CLI execution"

• Check pipeline logs for Claude Code CLI installation issues
• Verify branch follows auto-doc/ISSUE-KEY format
• Ensure JIRA issue has auto-doc label

"BITBUCKET_TOKEN environment variable is required"

• Verify the app password has correct permissions
• Check if the token hasn't expired
• Ensure variable is marked as Secured

Getting Help

1. Check the pipeline logs in Bitbucket
2. Verify all Repository Variables are configured
3. Ensure Secured variables are properly encrypted

📋 Environment Variable Reference

Variable	Required	Type	Description	Example
JIRA_URL	Yes	Regular	Your Atlassian instance URL	https://superna.atlassian.net
JIRA_EMAIL	Yes	Regular	Your Atlassian account email	user@superna.com
JIRA_API_TOKEN	Yes	Secured	JIRA API token	ATATT3xFfGF0...
ANTHROPIC_API_KEY	Yes	Secured	Anthropic API key	sk-ant-api03-...
BITBUCKET_TOKEN	Yes	Secured	Bitbucket app password	your-app-password
BITBUCKET_WORKSPACE	No	Regular	Bitbucket workspace	superna (default)
BITBUCKET_REPO_SLUG	No	Regular	Repository name	public-documentation (default)
DEFAULT_REVIEWERS	No	Regular	Default PR reviewers	john.doe,jane.smith