Back to Details

atlassian-readonly-skills

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Atlassian Readonly Skills

Atlassian只读工具集

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
.
用于Jira、Confluence和Bitbucket集成的只读Python工具集，支持Cloud和Data Center部署。
注意：这是一个只读版本，排除了所有写入操作（创建、更新、删除）。如需包含写入操作的完整功能，请使用
atlassian-skills
。

Configuration

配置

Two configuration modes are supported:
支持两种配置模式：

Mode 1: Environment Variables (Traditional)

模式1：环境变量（传统方式）

Set environment variables based on your deployment type. This mode is used when 
credentials
parameter is not provided to skill functions.
根据部署类型设置环境变量。当未向工具函数提供
credentials
参数时，将使用此模式。

Cloud (API Token)

Cloud（API Token）

bash
undefined
bash
undefined

Jira Cloud

Jira Cloud

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

Confluence Cloud

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
CONFLUENCE_URL=https://your-company.atlassian.net/wiki CONFLUENCE_USERNAME=your.email@company.com CONFLUENCE_API_TOKEN=your_api_token

在以下地址生成API Token：https://id.atlassian.com/manage-profile/security/api-tokens

Data Center / Server (PAT Token)

Data Center / Server（PAT Token）

bash
undefined
bash
undefined

Jira Data Center

Jira Data Center

JIRA_URL=https://jira.your-company.com JIRA_PAT_TOKEN=your_pat_token
JIRA_URL=https://jira.your-company.com JIRA_PAT_TOKEN=your_pat_token

Confluence Data Center

Confluence Data Center

CONFLUENCE_URL=https://confluence.your-company.com CONFLUENCE_PAT_TOKEN=your_pat_token
CONFLUENCE_URL=https://confluence.your-company.com CONFLUENCE_PAT_TOKEN=your_pat_token

Bitbucket Server/Data Center

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.
BITBUCKET_URL=https://bitbucket.your-company.com BITBUCKET_PAT_TOKEN=your_pat_token

> **注意**：如果同时提供两种Token，PAT Token将优先生效。

Mode 2: Parameter-Based (Agent Environments)

模式2：基于参数（Agent环境）

When deploying skills in Agent environments where environment variables are not available, pass credentials directly to skill functions using the 
AtlassianCredentials
object.
python
from scripts._common import AtlassianCredentials, check_available_skills
from scripts.jira_issues import jira_get_issue
在无法使用环境变量的Agent环境中部署工具时，可通过
AtlassianCredentials
对象直接将凭据传递给工具函数。
python
from scripts._common import AtlassianCredentials, check_available_skills
from scripts.jira_issues import jira_get_issue

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"
)
credentials = AtlassianCredentials( # Jira配置 jira_url="https://your-company.atlassian.net", jira_username="your.email@company.com", jira_api_token="your_api_token",
# Confluence配置（可选）
confluence_url="https://your-company.atlassian.net/wiki",
confluence_username="your.email@company.com",
confluence_api_token="your_api_token",

# Bitbucket配置（可选）
# 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"}
availability = check_available_skills(credentials) print(availability["available_services"]) # ["jira", "confluence"] print(availability["unavailable_services"]) # {"bitbucket": "Missing bitbucket_url"}

Use skills with credentials parameter

使用带credentials参数的工具

result = jira_get_issue( issue_key="PROJ-123", credentials=credentials # Pass credentials here )
undefined
result = jira_get_issue( issue_key="PROJ-123", credentials=credentials # 在此处传递凭据 )
undefined

Partial Service Configuration

部分服务配置

You can configure only the services you need. Services without complete credentials will be unavailable:
python
undefined
您可以仅配置所需的服务。未完成凭据配置的服务将无法使用：
python
undefined

Only configure Jira

仅配置Jira

credentials = AtlassianCredentials( jira_url="https://your-company.atlassian.net", jira_username="your.email@company.com", jira_api_token="your_api_token" )
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工具可正常使用

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

Confluence/Bitbucket skills will fail with ConfigurationError

Confluence/Bitbucket工具将因ConfigurationError失败

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

For credentials object fields and authentication options, see the full documentation in `atlassian-skills`.
confluence_get_page("Page Title", "SPACE", credentials=credentials) # ✗ 失败

有关凭据对象字段和认证选项，请查看`atlassian-skills`中的完整文档。

Core Workflow

核心工作流

Using Environment Variables

使用环境变量

python
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
python
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

1. 获取Jira问题

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

2. Search for issues

2. 搜索问题

result = jira_search( jql="project = PROJ AND status = 'In Progress'", fields="summary,status,assignee", limit=50 ) issues = json.loads(result)
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

3. 获取Confluence页面

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

Using Credentials Parameter (Agent Mode)

使用凭据参数（Agent模式）

python
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
python
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" )
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

1. 使用凭据获取Jira问题

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

2. Search for issues with credentials

2. 使用凭据搜索问题

result = jira_search( jql="project = PROJ AND status = 'In Progress'", fields="summary,status,assignee", limit=50, credentials=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

3. 使用凭据获取Confluence页面

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

Available Utilities

可用工具

Jira Issue Management (
scripts.jira_issues
)

Jira问题管理（
scripts.jira_issues
）

python
from scripts.jira_issues import jira_get_issue
python
from scripts.jira_issues import jira_get_issue

Get issue by key

通过问题键获取问题

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

Jira Search (
scripts.jira_search
)

Jira搜索（
scripts.jira_search
）

python
from scripts.jira_search import jira_search, jira_search_fields
python
from scripts.jira_search import jira_search, jira_search_fields

Search with JQL

使用JQL搜索

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

Find field definitions

查找字段定义

jira_search_fields(keyword="custom")
undefined
jira_search_fields(keyword="custom")
undefined

Jira Workflow (
scripts.jira_workflow
)

Jira工作流（
scripts.jira_workflow
）

python
from scripts.jira_workflow import jira_get_transitions
python
from scripts.jira_workflow import jira_get_transitions

Get available transitions for an issue

获取问题的可用流转

jira_get_transitions(issue_key="PROJ-123")
undefined
jira_get_transitions(issue_key="PROJ-123")
undefined

Jira Agile (
scripts.jira_agile
)

Jira敏捷（
scripts.jira_agile
）

python
from scripts.jira_agile import (
    jira_get_agile_boards,
    jira_get_board_issues,
    jira_get_sprints_from_board,
    jira_get_sprint_issues
)
python
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")
jira_get_agile_boards(project_key="PROJ")

Get issues on a board

获取看板上的问题

jira_get_board_issues(board_id=1, jql="status = 'In Progress'")
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")
jira_get_sprints_from_board(board_id=1, state="active")

Get issues in a sprint

获取迭代中的问题

jira_get_sprint_issues(sprint_id=42)
undefined
jira_get_sprint_issues(sprint_id=42)
undefined

Jira Links (
scripts.jira_links
)

Jira链接（
scripts.jira_links
）

python
from scripts.jira_links import jira_get_link_types
python
from scripts.jira_links import jira_get_link_types

Get available link types

获取可用的链接类型

jira_get_link_types()
undefined
jira_get_link_types()
undefined

Jira Worklog (
scripts.jira_worklog
)

Jira工作日志（
scripts.jira_worklog
）

python
from scripts.jira_worklog import jira_get_worklog
python
from scripts.jira_worklog import jira_get_worklog

Get worklog entries for an issue

获取问题的工作日志条目

jira_get_worklog(issue_key="PROJ-123")
undefined
jira_get_worklog(issue_key="PROJ-123")
undefined

Jira Projects (
scripts.jira_projects
)

Jira项目（
scripts.jira_projects
）

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

Get all projects

获取所有项目

jira_get_all_projects()
jira_get_all_projects()

Get issues in a project

获取项目中的问题

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

Get project versions

获取项目版本

jira_get_project_versions(project_key="PROJ")
undefined
jira_get_project_versions(project_key="PROJ")
undefined

Jira Users (
scripts.jira_users
)

Jira用户（
scripts.jira_users
）

python
from scripts.jira_users import jira_get_user_profile
python
from scripts.jira_users import jira_get_user_profile

Get user profile

获取用户资料

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

Confluence Pages (
scripts.confluence_pages
)

Confluence页面（
scripts.confluence_pages
）

python
from scripts.confluence_pages import confluence_get_page
python
from scripts.confluence_pages import confluence_get_page

Get page by title

通过标题获取页面

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

Get page by ID

通过ID获取页面

confluence_get_page(page_id="12345")
undefined
confluence_get_page(page_id="12345")
undefined

Confluence Search (
scripts.confluence_search
)

Confluence搜索（
scripts.confluence_search
）

python
from scripts.confluence_search import confluence_search
python
from scripts.confluence_search import confluence_search

Search with CQL

使用CQL搜索

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

Confluence Comments (
scripts.confluence_comments
)

Confluence评论（
scripts.confluence_comments
）

python
from scripts.confluence_comments import confluence_get_comments
python
from scripts.confluence_comments import confluence_get_comments

Get comments on a page

获取页面的评论

confluence_get_comments(page_id="12345")
undefined
confluence_get_comments(page_id="12345")
undefined

Confluence Labels (
scripts.confluence_labels
)

Confluence标签（
scripts.confluence_labels
）

python
from scripts.confluence_labels import confluence_get_labels
python
from scripts.confluence_labels import confluence_get_labels

Get labels on a page

获取页面的标签

confluence_get_labels(page_id="12345")
undefined
confluence_get_labels(page_id="12345")
undefined

Bitbucket Projects (
scripts.bitbucket_projects
)

Bitbucket项目（
scripts.bitbucket_projects
）

python
from scripts.bitbucket_projects import (
    bitbucket_list_projects,
    bitbucket_list_repositories
)
python
from scripts.bitbucket_projects import (
    bitbucket_list_projects,
    bitbucket_list_repositories
)

List all projects

列出所有项目

bitbucket_list_projects(limit=25)
bitbucket_list_projects(limit=25)

List repositories in a project

列出项目中的仓库

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

Bitbucket Pull Requests (
scripts.bitbucket_pull_requests
)

Bitbucket拉取请求（
scripts.bitbucket_pull_requests
）

python
from scripts.bitbucket_pull_requests import (
    bitbucket_get_pull_request,
    bitbucket_get_pr_diff
)
python
from scripts.bitbucket_pull_requests import (
    bitbucket_get_pull_request,
    bitbucket_get_pr_diff
)

Get PR details

获取PR详情

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

Get PR diff

获取PR差异

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

Bitbucket Files & Search (
scripts.bitbucket_files
)

Bitbucket文件与搜索（
scripts.bitbucket_files
）

python
from scripts.bitbucket_files import (
    bitbucket_get_file_content,
    bitbucket_search
)
python
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" )
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 )
undefined
bitbucket_search( query="def authenticate", project_key="PROJ", search_type="code", limit=25 )
undefined

Bitbucket Commits (
scripts.bitbucket_commits
)

Bitbucket提交（
scripts.bitbucket_commits
）

python
from scripts.bitbucket_commits import (
    bitbucket_get_commits,
    bitbucket_get_commit
)
python
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 )
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" )
undefined
bitbucket_get_commit( project_key="PROJ", repository_slug="my-repo", commit_id="1da11eaec25aed8b251de24841885c91493b3173" )
undefined

Response Data Structures

响应数据结构

All functions return JSON strings with flattened data structures (not nested API responses).
所有函数返回的JSON字符串均为扁平化数据结构（而非嵌套的API响应）。

Jira Issue Structure

Jira问题结构

json
{
  "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": {}
}
json
{
  "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

Confluence页面结构

json
{
  "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.
json
{
  "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"
}
注意：这些是简化后的结构。原始Jira API返回嵌套数据（例如
{"key": "...", "fields": {"summary": "...", "status": {"name": "..."}}}
），但本工具将其扁平化以方便使用。

Error Handling

错误处理

All functions return JSON strings. Check for errors:
python
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']}")
所有函数均返回JSON字符串。检查错误的方式如下：
python
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
  • ConfigurationError
    - 缺少环境变量
  • AuthenticationError
    - 凭据无效
  • ValidationError
    - 输入参数无效
  • NotFoundError
    - 资源未找到
  • APIError
    - Atlassian API错误
  • NetworkError
    - 连接问题

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
本工具提供：
  • 只读访问权限：仅查询和检索数据，不进行修改
  • Token效率优化：通过排除写入操作减少上下文大小
  • 安全性：防止意外修改数据
  • 灵活性：支持Cloud和Data Center部署
  • 一致性：统一的错误处理和响应格式
本工具不提供：
  • 写入操作（创建、更新、删除）
  • 直接API访问（请使用提供的函数）
  • Webhook处理或事件处理
  • 批量导入/导出操作
最佳实践：
  • 始终检查返回值是否存在错误
  • 使用JQL/CQL进行高效搜索
  • 如需写入操作，请使用完整的
    atlassian-skills
    包

Dependencies

依赖项

bash
pip install requests python-dotenv
Or use the requirements file:
bash
pip install -r requirements.txt
bash
pip install requests python-dotenv
或使用requirements文件：
bash
pip install -r requirements.txt