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 Authentication

Option 1: App Password (Recommended for pipelines)

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

Option 2: Bearer Token (OAuth)

If using OAuth-based authentication, obtain a Bearer token through your OAuth application flow.

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_BEARER_TOKEN	Secured	your-bearer-token	Bitbucket Bearer token (OAuth) - OR use Basic Auth below
BITBUCKET_USERNAME	Regular	your-username	Bitbucket username (for Basic Auth)
BITBUCKET_API_TOKEN	Secured	your-app-password	Bitbucket app password (for Basic Auth)
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)

Note: For Bitbucket authentication, use either:

• BITBUCKET_BEARER_TOKEN for OAuth Bearer token authentication, OR
• BITBUCKET_USERNAME + BITBUCKET_API_TOKEN for Basic authentication with app password

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 authentication required"

• Verify you have either:
  • BITBUCKET_BEARER_TOKEN set, OR
  • Both BITBUCKET_USERNAME and BITBUCKET_API_TOKEN set
• Check if the token/app password hasn't expired
• Verify the app password has correct permissions (Repositories: Write, Pull requests: Write)
• Ensure variables are 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_BEARER_TOKEN	Conditional*	Secured	Bitbucket Bearer token (OAuth)	your-bearer-token
BITBUCKET_USERNAME	Conditional*	Regular	Bitbucket username (Basic Auth)	your-username
BITBUCKET_API_TOKEN	Conditional*	Secured	Bitbucket app password (Basic Auth)	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

* Bitbucket Authentication: Either BITBUCKET_BEARER_TOKEN OR (BITBUCKET_USERNAME + BITBUCKET_API_TOKEN) is required.