atlassian · diff

git:20261013.316320c to git:20261013.89ccbeb

19 added, 402 removed. Audit A to A.

---

name: atlassian

description: >-

Практическая работа с Atlassian через Python-утилиты: Jira (задачи, JQL-поиск,

workflow-переходы, agile-доски, спринты, worklog, ссылки, версии), Confluence

(страницы, CQL-поиск, комментарии, метки, пространства, красивые статьи в

storage format) и Bitbucket Server/DC (pull requests, код, коммиты).

Поддерживает Cloud (API token) и Data Center/Server (PAT). Используй этот

skill при любых задачах по Jira/Confluence: создать задачу, найти задачи по

JQL, перевести статус, залогировать время, создать спринт, найти страницу в

Confluence, создать/обновить страницу, добавить метку или комментарий,

оформить статью с макросами, создать pull request, посмотреть историю

коммитов. Триггеры: jira, confluence, bitbucket, atlassian, jql, cql,

задача, тикет, спринт, доска, worklog, страница в confluence, wiki,

create issue, transition, sprint board, pull request.

metadata:

source: https://github.com/langpingxue/atlassian-skills

upstream_commit: "21ae2e5"

upstream_synced: "2026-10-13"

license: MIT

---

# Atlassian Skills

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

> Vendored from [langpingxue/atlassian-skills](https://github.com/langpingxue/atlassian-skills) (MIT). Local changes: renamed skill to `atlassian`, import fixes in `scripts/bitbucket_*.py`, added `.env.example` and `agents/openai.yaml`.

## Reference files

- [`references/jql-cql-cookbook.md`](references/jql-cql-cookbook.md) — готовые JQL-запросы для `jira_search` и CQL-запросы для `confluence_search`: мои задачи, баги, просрочки, спринты, поиск страниц, метки.

+ - [`references/utilities.md`](references/utilities.md) — all utility functions, signatures, response data structures.

- [`references/confluence-formatting.md`](references/confluence-formatting.md) — хранилище format для красивых статей: панели info/note/warning, оглавление `toc`, блоки кода, таблицы со `status`-бейджами, чек-листы, `expand`, layout, изображения, шаблон Meeting Notes.

## 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.

#### Cloud (API Token)

```bash

# 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)

```bash

# 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)

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_create_issue, 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"

)

# 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_create_issue(

project_key="PROJ",

summary="New task",

issue_type="Task",

credentials=credentials # Pass credentials here

)

```

#### Partial Service Configuration

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

```python

# 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

```

#### Credentials Object Fields

```python

AtlassianCredentials(

# Jira

jira_url: Optional[str] = None,

jira_username: Optional[str] = None,

jira_api_token: Optional[str] = None,

jira_pat_token: Optional[str] = None,

jira_api_version: Optional[str] = None, # '2' or '3', auto-detected if not set

jira_ssl_verify: bool = False,

# Confluence

confluence_url: Optional[str] = None,

confluence_username: Optional[str] = None,

confluence_api_token: Optional[str] = None,

confluence_pat_token: Optional[str] = None,

confluence_api_version: Optional[str] = None,

confluence_ssl_verify: bool = False,

# Bitbucket

bitbucket_url: Optional[str] = None,

bitbucket_username: Optional[str] = None,

bitbucket_api_token: Optional[str] = None,

bitbucket_pat_token: Optional[str] = None,

bitbucket_api_version: Optional[str] = None,

bitbucket_ssl_verify: bool = False

)

```

For each service, provide either:

- PAT Token (for Data Center/Server): `{service}_pat_token`

- Username + API Token (for Cloud): `{service}_username` + `{service}_api_token`

## Core Workflow

### Using Environment Variables

```python

from scripts.jira_issues import jira_create_issue, jira_get_issue

from scripts.confluence_pages import confluence_create_page

import json

# 1. Create a Jira issue

result = jira_create_issue(

project_key="PROJ",

summary="Implement new feature",

issue_type="Task",

description="Feature description here",

priority="High"

)

issue = json.loads(result)

print(f"Created: {issue['key']}")

# 2. Get issue details

result = jira_get_issue(issue_key="PROJ-123")

issue = json.loads(result)

# 3. Create a Confluence page

result = confluence_create_page(

space_key="DEV",

title="Feature Documentation",

content="<p>Documentation content here</p>"

)

```

### Using Credentials Parameter (Agent Mode)

```python

from scripts._common import AtlassianCredentials

from scripts.jira_issues import jira_create_issue, jira_get_issue

from scripts.confluence_pages import confluence_create_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. Create a Jira issue with credentials

result = jira_create_issue(

project_key="PROJ",

summary="Implement new feature",

issue_type="Task",

description="Feature description here",

priority="High",

credentials=credentials # Pass credentials

)

issue = json.loads(result)

print(f"Created: {issue['key']}")

# 2. Get issue details with credentials

result = jira_get_issue(

issue_key="PROJ-123",

credentials=credentials

)

issue = json.loads(result)

# 3. Create a Confluence page with credentials

result = confluence_create_page(

space_key="DEV",

title="Feature Documentation",

content="<p>Documentation content here</p>",

credentials=credentials

)

```

## Available Utilities

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

- ```python

- from scripts.jira_issues import (

- jira_get_issue, # Get issue by key

- jira_create_issue, # Create new issue

- jira_update_issue, # Update existing issue

- jira_delete_issue, # Delete issue

- jira_add_comment # Add comment to issue

- )

- # Create issue with full options

- jira_create_issue(

- project_key="PROJ",

- summary="Bug fix",

- issue_type="Bug",

- description="Description",

- assignee="user@company.com",

- priority="High",

- labels=["urgent", "backend"],

- custom_fields={

- "customfield_10001": "Custom value",

- "customfield_10002": 123

- }

- )

- ```

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

- ```python

- 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`)

- ```python

- from scripts.jira_workflow import jira_get_transitions, jira_transition_issue

- # Get available transitions

- jira_get_transitions(issue_key="PROJ-123")

- # Transition issue to new status

- jira_transition_issue(

- issue_key="PROJ-123",

- transition_id="31",

- comment="Moving to review"

- )

- ```

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

- ```python

- from scripts.jira_agile import (

- jira_get_agile_boards,

- jira_get_sprints_from_board,

- jira_get_sprint_issues,

- jira_create_sprint,

- jira_update_sprint

- )

- # Get boards

- jira_get_agile_boards(project_key="PROJ")

- # Get active sprints

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

- # Create new sprint

- jira_create_sprint(

- board_id=1,

- sprint_name="Sprint 5",

- start_date="2024-01-15",

- end_date="2024-01-29",

- goal="Complete feature X"

- )

- ```

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

- ```python

- from scripts.jira_links import (

- jira_get_link_types,

- jira_create_issue_link,

- jira_link_to_epic,

- jira_remove_issue_link

- )

- # Link issues

- jira_create_issue_link(

- link_type="Blocks",

- inward_issue_key="PROJ-123",

- outward_issue_key="PROJ-456"

- )

- # Link to epic

- jira_link_to_epic(issue_key="PROJ-123", epic_key="PROJ-100")

- ```

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

- ```python

- from scripts.jira_worklog import jira_get_worklog, jira_add_worklog

- # Add time spent

- jira_add_worklog(

- issue_key="PROJ-123",

- time_spent="2h 30m",

- comment="Code review"

- )

- ```

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

- ```python

- from scripts.jira_projects import (

- jira_get_all_projects,

- jira_get_project_issues,

- jira_get_project_versions,

- jira_create_version

- )

- # Get all projects

- jira_get_all_projects()

- # Create version

- jira_create_version(

- project_key="PROJ",

- name="v2.0.0",

- release_date="2024-03-01"

- )

- ```

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

- ```python

- from scripts.confluence_pages import (

- confluence_get_page,

- confluence_create_page,

- confluence_update_page,

- confluence_delete_page

- )

- # Get page by title

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

- # Create page with parent

- confluence_create_page(

- space_key="DEV",

- title="API Documentation",

- content="<h1>API Docs</h1><p>Content here</p>",

- parent_id="12345"

- )

- # Update page

- confluence_update_page(

- page_id="67890",

- title="Updated Title",

- content="<p>New content</p>"

- )

- ```

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

- ```python

- 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`)

- ```python

- from scripts.confluence_comments import confluence_get_comments, confluence_add_comment

- # Add comment

- confluence_add_comment(

- page_id="12345",

- content="Great documentation!"

- )

- ```

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

- ```python

- from scripts.confluence_labels import (

- confluence_get_labels,

- confluence_add_label,

- confluence_remove_label

- )

- # Manage labels

- confluence_add_label(page_id="12345", name="reviewed")

- confluence_remove_label(page_id="12345", name="draft")

- ```

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

- ```python

- 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`)

- ```python

- from scripts.bitbucket_pull_requests import (

- bitbucket_create_pull_request,

- bitbucket_get_pull_request,

- bitbucket_merge_pull_request,

- bitbucket_decline_pull_request,

- bitbucket_add_pr_comment,

- bitbucket_get_pr_diff

- )

- # Create a pull request

- bitbucket_create_pull_request(

- project_key="PROJ",

- repository_slug="my-repo",

- title="Feature: Add new API",

- source_branch="feature/new-api",

- target_branch="master",

- description="Implements the new API endpoint",

- reviewers=["john.doe", "jane.smith"]

- )

- # Get PR details

- bitbucket_get_pull_request(

- project_key="PROJ",

- repository_slug="my-repo",

- pr_id=123

- )

- # Merge PR (version from get_pull_request)

- bitbucket_merge_pull_request(

- project_key="PROJ",

- repository_slug="my-repo",

- pr_id=123,

- version=5,

- strategy="squash"

- )

- # Add comment to PR

- bitbucket_add_pr_comment(

- project_key="PROJ",

- repository_slug="my-repo",

- pr_id=123,

- text="LGTM!"

- )

- ```

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

- ```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"

- )

- # Search code

- bitbucket_search(

- query="def authenticate",

- project_key="PROJ",

- search_type="code",

- limit=25

- )

- ```

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

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

- )

- # Get details of a specific commit

- bitbucket_get_commit(

- project_key="PROJ",

- repository_slug="my-repo",

- commit_id="1da11eaec25aed8b251de24841885c91493b3173"

- )

- ```

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

- ```python

- from scripts.jira_users import jira_get_user_profile

- # Get Jira user profile

- jira_get_user_profile(

- user_identifier="user@company.com",

- credentials=credentials # Optional

- )

- ```

- ## Function Signature Pattern

- All skill functions follow this signature pattern:

- ```python

- def skill_function(

- required_param1: str,

- required_param2: str,

- optional_param: Optional[str] = None,

- credentials: Optional[AtlassianCredentials] = None # Always last parameter

- ) -> str:

- """Function description.

- Args:

- required_param1: Description

- required_param2: Description

- optional_param: Description (optional)

- credentials: Optional AtlassianCredentials for Agent environments.

- If not provided, uses environment variables.

- Returns:

- JSON string with result or error information

- """

- ```

- The `credentials` parameter is:

- - **Optional**: If not provided, configuration loads from environment variables

- - **Always the last parameter**: Maintains consistent function signatures

- - **Backward compatible**: Existing code without credentials parameter continues to work

- ## Response Data Structures

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

- ### Jira Issue Structure

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

+ Full function list, signatures and response data structures: [`references/utilities.md`](references/utilities.md). Modules:

- ```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 Issue Management (`scripts.jira_issues`)

+ - Jira Search (`scripts.jira_search`)

+ - Jira Workflow (`scripts.jira_workflow`)

+ - Jira Agile (`scripts.jira_agile`)

+ - Jira Links (`scripts.jira_links`)

+ - Jira Worklog (`scripts.jira_worklog`)

+ - Jira Projects (`scripts.jira_projects`)

+ - Confluence Pages (`scripts.confluence_pages`)

+ - Confluence Search (`scripts.confluence_search`)

+ - Confluence Comments (`scripts.confluence_comments`)

+ - Confluence Labels (`scripts.confluence_labels`)

+ - Bitbucket Projects (`scripts.bitbucket_projects`)

+ - Bitbucket Pull Requests (`scripts.bitbucket_pull_requests`)

+ - Bitbucket Files & Search (`scripts.bitbucket_files`)

+ - Bitbucket Commits (`scripts.bitbucket_commits`)

+ - Jira Users (`scripts.jira_users`)

- > **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.

+ All functions follow one pattern: keyword arguments, optional `credentials=`, and a JSON-serialisable dict/list result (see the reference).

## 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']}")

```

### 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:

- **Utilities**: Ready-to-use functions for common Atlassian operations

- **Flexibility**: Support for both Cloud and Data Center deployments

- **Dual Configuration**: Environment variables OR parameter-based credentials

- **Agent-Ready**: Works in environments without environment variable access

- **Consistency**: Unified error handling and response format

- **Backward Compatible**: Existing code continues to work without changes

It does NOT provide:

- 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

- Batch operations when possible to reduce API calls

- In Agent environments, check service availability before calling skills:

```python

availability = check_available_skills(credentials)

if "jira" in availability["available_services"]:

result = jira_get_issue("PROJ-123", credentials=credentials)

```

## Dependencies

```bash

pip install requests python-dotenv

```

Or use the requirements file:

```bash

pip install -r requirements.txt

```