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

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

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

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