Connectors

Direct API connectors allow fetching data from Jira, Confluence, GitHub and GitLab without manually exporting files. They are used via scheme URIs in the -s flag.

intake init "Sprint tasks" -s jira://PROJ/sprint/42
intake init "RFC review" -s confluence://ENG/Architecture-RFC
intake init "Bug triage" -s github://org/repo/issues?labels=bug
intake init "Sprint review" -s gitlab://team/project/issues?labels=sprint

Prerequisites

Installation

Connectors require optional dependencies:

pip install "intake-ai-cli[connectors]"

This installs atlassian-python-api (Jira, Confluence), PyGithub (GitHub) and python-gitlab (GitLab).

Configuration

Configure credentials in .intake.yaml and environment variables:

connectors:
  jira:
    url: "https://company.atlassian.net"
    token_env: JIRA_API_TOKEN
    email_env: JIRA_EMAIL
  confluence:
    url: "https://company.atlassian.net/wiki"
    token_env: CONFLUENCE_API_TOKEN
    email_env: CONFLUENCE_EMAIL
  github:
    token_env: GITHUB_TOKEN
  gitlab:
    url: "https://gitlab.example.com"
    token_env: GITLAB_TOKEN

export JIRA_API_TOKEN=your-api-token
export JIRA_EMAIL=dev@company.com
export CONFLUENCE_API_TOKEN=your-api-token
export CONFLUENCE_EMAIL=dev@company.com
export GITHUB_TOKEN=ghp_your-personal-access-token

# GitLab
export GITLAB_TOKEN=glpat-your-personal-access-token

Verification

intake doctor    # verifies credentials if connectors are configured

Jira

Fetches issues directly from the Jira Cloud or Server REST API.

Supported URIs

URI	What it does
`jira://PROJ-123`	A single issue
`jira://PROJ-123,PROJ-124,PROJ-125`	Multiple issues separated by comma
`jira://PROJ?jql=sprint%20%3D%2042`	JQL search
`jira://PROJ/sprint/42`	All issues from a sprint

Examples

# A specific issue
intake init "Fix auth bug" -s jira://AUTH-456

# Multiple issues
intake init "Sprint review" -s jira://AUTH-456,AUTH-457,AUTH-458

# JQL search
intake init "P1 bugs" -s "jira://PROJ?jql=priority=Highest AND status!=Done"

# Full sprint
intake init "Sprint 42" -s jira://PROJ/sprint/42

Full configuration

connectors:
  jira:
    url: "https://company.atlassian.net"     # Required
    auth_type: token                          # token | oauth | api_key
    token_env: JIRA_API_TOKEN                 # Environment variable name
    email_env: JIRA_EMAIL                     # Email for authentication
    default_project: ""                       # Default project
    include_comments: true                    # Include comments
    max_comments: 5                           # Maximum comments per issue
    fields:                                   # Fields to retrieve
      - summary
      - description
      - labels
      - priority
      - status
      - issuelinks
      - comment

What it extracts

For each issue, the connector retrieves the same data that JiraParser extracts from JSON files:

Summary, description, priority, status
Labels and issue links (dependencies)
Comments (up to max_comments, with ADF support)

Data is saved as temporary JSON files compatible with JiraParser.

Confluence

Fetches pages directly from the Confluence Cloud or Server API.

Supported URIs

URI	What it does
`confluence://page/123456789`	Page by ID
`confluence://SPACE/Page-Title`	Page by space and title
`confluence://search?cql=space.key%3DENG`	CQL search

Examples

# Page by ID
intake init "RFC review" -s confluence://page/123456789

# Page by space and title
intake init "Architecture" -s confluence://ENG/System-Architecture

# CQL search
intake init "Team docs" -s "confluence://search?cql=space.key=ENG AND label=requirements"

Full configuration

connectors:
  confluence:
    url: "https://company.atlassian.net/wiki"  # Required
    auth_type: token                            # token | oauth
    token_env: CONFLUENCE_API_TOKEN
    email_env: CONFLUENCE_EMAIL
    default_space: ""                           # Default space
    include_child_pages: false                  # Include child pages
    max_depth: 1                                # Maximum depth

What it extracts

The connector downloads the page body in HTML format (storage or view format) and saves it as a temporary HTML file compatible with ConfluenceParser. It extracts:

HTML content of the page
Title and metadata
Child pages (if include_child_pages: true)

GitHub

Fetches issues directly from the GitHub API.

Supported URIs

URI	What it does
`github://org/repo/issues/42`	A single issue
`github://org/repo/issues/42,43,44`	Multiple issues separated by comma
`github://org/repo/issues?labels=bug&state=open`	Filtered issues

Filter parameters

Parameter	Description	Example
`labels`	Filter by labels (comma-separated)	`labels=bug,urgent`
`state`	Issue state	`state=open`, `state=closed`, `state=all`
`milestone`	Filter by milestone	`milestone=v2.0`

Examples

# A specific issue
intake init "Fix #42" -s github://org/repo/issues/42

# Multiple issues
intake init "Sprint items" -s github://org/repo/issues/42,43,44

# All open bugs
intake init "Bug triage" -s "github://org/repo/issues?labels=bug&state=open"

# Issues from a milestone
intake init "v2.0 features" -s "github://org/repo/issues?milestone=v2.0&state=all"

Full configuration

connectors:
  github:
    token_env: GITHUB_TOKEN      # Environment variable with the PAT
    default_repo: ""              # Default repo (e.g.: "org/repo")

Limits

Maximum 50 issues per query
Maximum 10 comments per issue
Requires a Personal Access Token with read permissions on the repository

What it extracts

Issues are saved as temporary JSON compatible with GithubIssuesParser:

Number, title, body, state
Labels, assignees, milestone
Comments (up to 10 per issue)
Cross-references (#NNN) in body and comments

GitLab

Fetches issues directly from the GitLab Cloud API or self-hosted instances (CE/EE).

Supported URIs

URI	What it does
`gitlab://group/project/issues/42`	A single issue
`gitlab://group/project/issues/42,43,44`	Multiple issues separated by comma
`gitlab://group/project/issues?labels=bug&state=opened`	Filtered issues
`gitlab://group/project/milestones/3/issues`	Issues from a milestone

Filter parameters

Parameter	Description	Example
`labels`	Filter by labels (comma-separated)	`labels=bug,urgent`
`state`	Issue state	`state=opened`, `state=closed`
`milestone`	Filter by milestone	`milestone=v2.0`
`assignee_username`	Filter by assigned user	`assignee_username=jdoe`
`search`	Text search	`search=login`
`order_by`	Sort by field	`order_by=updated_at`
`sort`	Sort direction	`sort=asc`

Examples

# A specific issue
intake init "Fix auth bug" -s gitlab://team/backend/issues/42

# Multiple issues
intake init "Sprint review" -s gitlab://team/backend/issues/42,43,44

# Open bugs
intake init "Bug triage" -s "gitlab://team/backend/issues?labels=bug&state=opened"

# Issues from a milestone
intake init "v2.0 features" -s gitlab://team/backend/milestones/3/issues

# Nested groups
intake init "Platform tasks" -s gitlab://org/team/subgroup/project/issues?state=opened

Full configuration

connectors:
  gitlab:
    url: "https://gitlab.example.com"           # Required. Default: https://gitlab.com
    token_env: GITLAB_TOKEN                      # Environment variable with the access token
    auth_type: token                              # token | oauth
    default_project: ""                           # Default project
    include_comments: true                        # Include discussion notes
    include_merge_requests: false                 # Include linked MRs
    max_notes: 10                                 # Max notes per issue
    ssl_verify: true                              # Verify SSL certificates

Nested groups

GitLab supports nested groups (e.g.: org/team/subgroup/project). The connector automatically detects the separation between the project path and the resource by looking for the issues or milestones keywords in the URI.

Limits

Maximum 50 issues per query
Maximum 10 notes per issue (configurable via max_notes)
Requires a Personal Access Token with read_api scope

What it extracts

Issues are saved as temporary JSON compatible with GitlabIssuesParser:

IID, title, description, state
Labels, milestone, weight, assignees
Task completion status (checkbox progress)
Discussion notes (non-system, up to max_notes)
Linked merge requests (if include_merge_requests: true)
Metadata: author, due_date, created_at, updated_at, web_url

Self-hosted instances

For instances with self-signed certificates:

connectors:
  gitlab:
    url: "https://gitlab.internal.company.com"
    ssl_verify: false    # Disable SSL verification

Protocol

Connectors implement the ConnectorPlugin protocol:

@runtime_checkable
class ConnectorPlugin(Protocol):
    @property
    def meta(self) -> PluginMeta: ...

    @property
    def uri_schemes(self) -> list[str]: ...

    def can_handle(self, uri: str) -> bool: ...
    async def fetch(self, uri: str) -> list[FetchedSource]: ...
    def validate_config(self) -> list[str]: ...

The fetch() method is async and returns a list of FetchedSource:

@dataclass
class FetchedSource:
    local_path: str          # Path to the downloaded temporary file
    original_uri: str        # Original URI (e.g.: "jira://PROJ-123")
    format_hint: str         # Hint for the parser (e.g.: "jira", "confluence")
    metadata: dict[str, str] # Additional metadata

Temporary files are passed to the parser registry to be processed normally.

Creating an external connector

Create a Python package that implements ConnectorPlugin
Register as an entry_point in the intake.connectors group
The connector will be automatically discovered

# pyproject.toml
[project.entry-points."intake.connectors"]
asana = "my_plugin.connector:AsanaConnector"

See Plugins for more details.