atlassian-readonly-skills（Atlassian 只读技能）

Atlassian Readonly Skills

Read-only Python utilities for Jira, Confluence, and Bitbucket integration, supporting both Cloud and Data Center deployments.

Note: This is a read-only variant that excludes all write operations (create, update, delete). For full functionality including write operations, use atlassian-skills.

FieldWorks / SIL JIRA Integration

LT-prefixed tickets (e.g., LT-22382, LT-19288) are JIRA issues from SIL's JIRA instance:

• Base URL: https://jira.sil.org
• Browse URL: https://jira.sil.org/browse/LT-XXXXX
• Project key: LT (Language Technology)

Trigger patterns: Use this skill when you see:

• LT-prefixed identifiers in user queries, code comments, commit messages, or git log output
• References to jira.sil.org URLs
• Requests to "look up" or "check" a JIRA ticket

⚠️ Critical: Always Use Python Scripts

NEVER attempt to:

• Browse to jira.sil.org URLs directly (requires authentication)
• Use fetch_webpage or similar tools on JIRA URLs
• Use GitHub issue tools for LT-* tickets

ALWAYS use these Python modules. The scripts are Python modules (not CLI tools), so use them via inline Python or import:

# Get a single issue (inline Python one-liner)
python -c "import sys; sys.path.insert(0, '.github/skills/atlassian-readonly-skills/scripts'); from jira_issues import jira_get_issue; print(jira_get_issue('LT-22382'))"

# Search for issues (JQL query)
python -c "import sys; sys.path.insert(0, '.github/skills/atlassian-readonly-skills/scripts'); from jira_search import jira_search; print(jira_search('project = LT AND status = Open'))"

# Get issue workflow transitions
python -c "import sys; sys.path.insert(0, '.github/skills/atlassian-readonly-skills/scripts'); from jira_workflow import jira_get_transitions; print(jira_get_transitions('LT-22382'))"

Use the script modules in this skill directly.

Configuration

Two configuration modes are supported:

Mode 1: Environment Variables (Traditional)

Set environment variables based on your deployment type. This mode is used when credentials parameter is not provided to skill functions.

SIL JIRA (Data Center / PAT Token)

# SIL JIRA instance for LT-* tickets
JIRA_URL=https://jira.sil.org
# Personal Access Token - generate at: https://jira.sil.org/secure/ViewProfile.jspa → Personal Access Tokens
JIRA_PAT_TOKEN=your_jira_pat_token_here

Cloud (API Token)

# Jira Cloud
JIRA_URL=https://your-company.atlassian.net
JIRA_USERNAME=your.email@company.com
JIRA_API_TOKEN=your_api_token

# Confluence Cloud
CONFLUENCE_URL=https://your-company.atlassian.net/wiki
CONFLUENCE_USERNAME=your.email@company.com
CONFLUENCE_API_TOKEN=your_api_token

Generate API tokens at: https://id.atlassian.com/manage-profile/security/api-tokens

Data Center / Server (PAT Token)

# Jira Data Center
JIRA_URL=https://jira.your-company.com
JIRA_PAT_TOKEN=your_pat_token

# Confluence Data Center
CONFLUENCE_URL=https://confluence.your-company.com
CONFLUENCE_PAT_TOKEN=your_pat_token

# Bitbucket Server/Data Center
BITBUCKET_URL=https://bitbucket.your-company.com
BITBUCKET_PAT_TOKEN=your_pat_token

Note: PAT Token takes precedence if both are provided.

Mode 2: Parameter-Based (Agent Environments)

Alternatively, call the scripts in this skill directly.

Create credentials object

credentials = AtlassianCredentials(# Jira configuration jira_url="https://your-company.atlassian.net", jira_username="your.email@company.com", jira_api_token="your_api_token",

# Confluence configuration (optional)
confluence_url="https://your-company.atlassian.net/wiki",
confluence_username="your.email@company.com",
confluence_api_token="your_api_token",

# Bitbucket configuration (optional)
# bitbucket_url="https://bitbucket.your-company.com",
# bitbucket_pat_token="your_pat_token"

)

Check which services are available

availability = check_available_skills(credentials) print(availability["available_services"]) # ["jira", "confluence"] print(availability["unavailable_services"]) # {"bitbucket": "Missing bitbucket_url"}

Use skills with credentials parameter

result = jira_get_issue(issue_key="PROJ-123", credentials=credentials # Pass credentials here)

#### Partial Service Configuration

You can configure only the services you need. Services without complete credentials will be unavailable:

Only configure Jira

credentials = AtlassianCredentials( jira_url="https://your-company.atlassian.net", jira_username="your.email@company.com", jira_api_token="your_api_token" )

Jira skills will work

jira_get_issue("PROJ-123", credentials=credentials) # ✓ Works

Confluence/Bitbucket skills will fail with ConfigurationError

confluence_get_page("Page Title", "SPACE", credentials=credentials) # ✗ Fails

For credentials object fields and authentication options, see the full documentation in `atlassian-skills`.

## Core Workflow

### Using Environment Variables

from scripts.jira_issues import jira_get_issue from scripts.jira_search import jira_search from scripts.confluence_pages import confluence_get_page import json

1. Get a Jira issue

result = jira_get_issue(issue_key="PROJ-123") issue = json.loads(result) print(f"Issue: {issue['key']} - {issue['summary']}")

2. Search for issues

result = jira_search( jql="project = PROJ AND status = 'In Progress'", fields="summary,status,assignee", limit=50 ) issues = json.loads(result)

3. Get a Confluence page

result = confluence_get_page(title="Feature Documentation", space_key="DEV") page = json.loads(result) print(f"Page: {page['title']}")

### Using Credentials Parameter (Agent Mode)

from scripts._common import AtlassianCredentials from scripts.jira_issues import jira_get_issue from scripts.jira_search import jira_search from scripts.confluence_pages import confluence_get_page import json

Create credentials

credentials = AtlassianCredentials( jira_url="https://company.atlassian.net", jira_username="user@company.com", jira_api_token="token123", confluence_url="https://company.atlassian.net/wiki", confluence_username="user@company.com", confluence_api_token="token123" )

1. Get a Jira issue with credentials

result = jira_get_issue( issue_key="PROJ-123", credentials=credentials ) issue = json.loads(result)

2. Search for issues with credentials

result = jira_search( jql="project = PROJ AND status = 'In Progress'", fields="summary,status,assignee", limit=50, credentials=credentials )

3. Get a Confluence page with credentials

result = confluence_get_page( title="Feature Documentation", space_key="DEV", credentials=credentials )

## Available Utilities

### Jira Issue Management (`scripts.jira_issues`)

from scripts.jira_issues import jira_get_issue

Get issue by key

jira_get_issue( issue_key="PROJ-123", credentials=credentials # Optional )

### Jira Search (`scripts.jira_search`)

from scripts.jira_search import jira_search, jira_search_fields

Search with JQL

jira_search( jql="project = PROJ AND status = 'In Progress'", fields="summary,status,assignee", limit=50 )

Find field definitions

jira_search_fields(keyword="custom")

### Jira Workflow (`scripts.jira_workflow`)

from scripts.jira_workflow import jira_get_transitions

Get available transitions for an issue

jira_get_transitions(issue_key="PROJ-123")

### Jira Agile (`scripts.jira_agile`)

from scripts.jira_agile import ( jira_get_agile_boards, jira_get_board_issues, jira_get_sprints_from_board, jira_get_sprint_issues )

Get boards

jira_get_agile_boards(project_key="PROJ")

Get issues on a board

jira_get_board_issues(board_id=1, jql="status = 'In Progress'")

Get sprints from a board

jira_get_sprints_from_board(board_id=1, state="active")

Get issues in a sprint

jira_get_sprint_issues(sprint_id=42)

### Jira Links (`scripts.jira_links`)

from scripts.jira_links import jira_get_link_types

Get available link types

jira_get_link_types()

### Jira Worklog (`scripts.jira_worklog`)

from scripts.jira_worklog import jira_get_worklog

Get worklog entries for an issue

jira_get_worklog(issue_key="PROJ-123")

### Jira Projects (`scripts.jira_projects`)

from scripts.jira_projects import ( jira_get_all_projects, jira_get_project_issues, jira_get_project_versions )

Get all projects

jira_get_all_projects()

Get issues in a project

jira_get_project_issues(project_key="PROJ", limit=100)

Get project versions

jira_get_project_versions(project_key="PROJ")

### Jira Users (`scripts.jira_users`)

from scripts.jira_users import jira_get_user_profile

Get user profile

jira_get_user_profile(user_identifier="user@company.com")

### Confluence Pages (`scripts.confluence_pages`)

from scripts.confluence_pages import confluence_get_page

Get page by title

confluence_get_page(title="Meeting Notes", space_key="TEAM")

Get page by ID

confluence_get_page(page_id="12345")

### Confluence Search (`scripts.confluence_search`)

from scripts.confluence_search import confluence_search

Search with CQL

confluence_search( query="space = DEV AND type = page AND text ~ 'API'", limit=25 )

### Confluence Comments (`scripts.confluence_comments`)

from scripts.confluence_comments import confluence_get_comments

Get comments on a page

confluence_get_comments(page_id="12345")

### Confluence Labels (`scripts.confluence_labels`)

from scripts.confluence_labels import confluence_get_labels

Get labels on a page

confluence_get_labels(page_id="12345")

### Bitbucket Projects (`scripts.bitbucket_projects`)

from scripts.bitbucket_projects import ( bitbucket_list_projects, bitbucket_list_repositories )

List all projects

bitbucket_list_projects(limit=25)

List repositories in a project

bitbucket_list_repositories(project_key="PROJ", limit=50)

### Bitbucket Pull Requests (`scripts.bitbucket_pull_requests`)

from scripts.bitbucket_pull_requests import ( bitbucket_get_pull_request, bitbucket_get_pr_diff )

Get PR details

bitbucket_get_pull_request( project_key="PROJ", repository_slug="my-repo", pr_id=123 )

Get PR diff

bitbucket_get_pr_diff( project_key="PROJ", repository_slug="my-repo", pr_id=123 )

### Bitbucket Files & Search (`scripts.bitbucket_files`)

from scripts.bitbucket_files import ( bitbucket_get_file_content, bitbucket_search )

Get file content

bitbucket_get_file_content( project_key="PROJ", repository_slug="my-repo", file_path="src/main.py", branch="develop" )

Search code

bitbucket_search( query="def authenticate", project_key="PROJ", search_type="code", limit=25 )

### Bitbucket Commits (`scripts.bitbucket_commits`)

from scripts.bitbucket_commits import ( bitbucket_get_commits, bitbucket_get_commit )

Get recent commits from a branch

bitbucket_get_commits( project_key="PROJ", repository_slug="my-repo", branch="master", limit=10 )

Get details of a specific commit

bitbucket_get_commit( project_key="PROJ", repository_slug="my-repo", commit_id="1da11eaec25aed8b251de24841885c91493b3173" )

## Response Data Structures

All functions return JSON strings with **flattened** data structures (not nested API responses).

### Jira Issue Structure

{ "key": "PROJ-123", "id": "10001", "summary": "Issue title", "description": "Issue description", "status": "In Progress", "issue_type": "Task", "priority": "High", "assignee": "user@company.com", "reporter": "reporter@company.com", "created": "2024-01-15T10:30:00.000+0000", "updated": "2024-01-16T14:20:00.000+0000", "labels": ["backend", "urgent"], "components": ["API", "Auth"], "custom_fields": {} }

### Confluence Page Structure

{ "id": "12345", "title": "Page Title", "space_key": "DEV", "status": "current", "created": "2024-01-15T10:30:00.000Z", "updated": "2024-01-16T14:20:00.000Z", "author": "user@company.com", "version": 3, "url": "https://company.atlassian.net/wiki/spaces/DEV/pages/12345" }

> **Note**: These are simplified structures. The original Jira API returns nested data like `{"key": "...", "fields": {"summary": "...", "status": {"name": "..."}}}`, but this skill flattens it for easier use.

## Error Handling

All functions return JSON strings. Check for errors:

import json

result = jira_get_issue(issue_key="PROJ-999") data = json.loads(result)

if not data.get("success", True): print(f"Error: {data['error']}") print(f"Type: {data['error_type']}") else: print(f"Issue: {data['key']}")

### Error Types

- `ConfigurationError` - Missing environment variables
- `AuthenticationError` - Invalid credentials
- `ValidationError` - Invalid input parameters
- `NotFoundError` - Resource not found
- `APIError` - Atlassian API error
- `NetworkError` - Connection issues

## Philosophy

This skill provides:

- **Read-Only Access**: Query and retrieve data without modification
- **Token Efficiency**: Reduced context size by excluding write operations
- **Safety**: Prevents accidental data modifications
- **Flexibility**: Support for both Cloud and Data Center deployments
- **Consistency**: Unified error handling and response format

It does NOT provide:

- Write operations (create, update, delete)
- Direct API access (use the provided functions instead)
- Webhook handling or event processing
- Bulk import/export operations

**Best practices**:

- Always check return values for errors
- Use JQL/CQL for efficient searching
- For write operations, use the full `atlassian-skills` package

## Dependencies

pip install requests python-dotenv

Or use the requirements file:

pip install -r requirements.txt