Authentication¶

GoJira supports multiple authentication methods to connect to your Jira instance.

Authentication Priority¶

The CLI checks authentication sources in this order:

CLI flags (--creds-file, --account)
Environment variables (JIRA_URL, JIRA_USER, JIRA_TOKEN)
goauth credentials file (~/.config/goauth/credentials.json)

Method 1: Environment Variables¶

Set these environment variables:

export JIRA_URL=https://your-instance.atlassian.net
export JIRA_USER=your-email@example.com
export JIRA_TOKEN=your-api-token

This is the recommended method for:

Local development
CI/CD pipelines
Docker containers
AI agent integrations

Non-interactive

Environment variables enable fully non-interactive operation, ideal for automation.

Method 2: goauth Credentials File¶

GoJira integrates with goauth for credential management.

Default Location¶

~/.config/goauth/credentials.json

File Format¶

{
  "credentials": {
    "jira-prod": {
      "service": "jira",
      "type": "basic",
      "basic": {
        "serverURL": "https://your-instance.atlassian.net",
        "username": "your-email@example.com",
        "password": "your-api-token"
      }
    },
    "jira-staging": {
      "service": "jira",
      "type": "basic",
      "basic": {
        "serverURL": "https://staging.atlassian.net",
        "username": "your-email@example.com",
        "password": "your-staging-token"
      }
    }
  }
}

Using a Specific Account¶

# Use account key from default credentials file
gojira search --jql "project = FOO" --account jira-prod

# Use custom credentials file
gojira search --jql "project = FOO" --creds-file ~/my-creds.json --account myaccount

Interactive Selection¶

If no --account is specified, goauth will interactively prompt you to select an account.

Getting an API Token¶

Jira Cloud¶

Go to Atlassian API Tokens
Click Create API token
Give it a descriptive name (e.g., "gojira CLI")
Copy the token immediately

Jira Server / Data Center¶

Use your Jira password or create a personal access token in your Jira Server settings.

Security Best Practices¶

Keep credentials secure

Never commit credentials to version control
Use environment variables in CI/CD
Restrict API token permissions when possible
Rotate tokens periodically

Using .envrc with direnv¶

For project-specific credentials, use direnv:

# .envrc (add to .gitignore)
export JIRA_URL=https://your-instance.atlassian.net
export JIRA_USER=your-email@example.com
export JIRA_TOKEN=your-api-token

Then run:

direnv allow

Troubleshooting¶

"authentication failed" Error¶

Verify your credentials are correct
Check that JIRA_URL includes https://
Ensure your API token hasn't expired
Verify you have access to the Jira project

Testing Authentication¶

# Test with a simple query
gojira search --jql "project = FOO" --max 1

# Check version (no auth required)
gojira version