How to Configure the PM Adapter for Jira or GitHub Integration in AIOX

Configure the PM adapter by creating a .aiox-pm-config.yaml file in your project root with pmTool.type set to jira or github-projects, then import getPMAdapter() from the factory to sync stories.

The SynkraAI/aiox-core repository provides a pluggable architecture for synchronizing local story files with external project management platforms. To configure the PM adapter for Jira or GitHub integration in AIOX, you must define your tool connection in a YAML configuration file and ensure the required authentication credentials are available in your environment.

How PM Adapters Work in AIOX

AIOX interacts with external PM tools through adapter classes that normalize operations like story creation, status updates, and bidirectional syncing.

The Factory Pattern

The PM Adapter Factory (.aiox-core/infrastructure/scripts/pm-adapter-factory.js) detects the presence of .aiox-pm-config.yaml at your project root, parses the pmTool.type field, and lazily instantiates the corresponding singleton adapter. If the configuration file is missing or specifies type: local, the factory falls back to the LocalAdapter, allowing AIOX to operate without external dependencies.

The Abstract Adapter Interface

Every PM adapter extends the abstract PMAdapter class (defined in scripts/pm-adapter.js) and implements four core methods:

• syncStory(storyPath) – Pushes a local YAML story file to the PM tool.
• pullStory(storyId) – Retrieves status updates from the PM tool.
• updateStatus(storyId, status) – Changes a story’s status in the external system.
• createStory(storyData) – Creates a new story directly in the PM tool.

The Jira Adapter (.aiox-core/infrastructure/integrations/pm-adapters/jira-adapter.js) implements these methods using the Jira REST API v3 over HTTPS, while the GitHub Projects Adapter (.aiox-core/infrastructure/integrations/pm-adapters/github-adapter.js) uses the GitHub CLI (gh) and GraphQL API v2.

Configuring the .aiox-pm-config.yaml File

Create this file at the same level as your package.json. The pmTool key selects the adapter, and the nested config object holds tool-specific settings.

Jira Adapter Configuration

Set type: jira and provide your instance URL and project key. Authentication relies on environment variables rather than hardcoded secrets.

pmTool:
  type: jira
  config:
    base_url: https://your-company.atlassian.net
    project_key: AIOX

Before running AIOX, export these environment variables:

export JIRA_EMAIL="your-email@company.com"
export JIRA_API_TOKEN="your_atlassian_api_token"

The adapter validates that base_url and project_key are present; if the token or email is missing, it logs a warning but still creates the adapter instance according to the validation logic in jira-adapter.js (lines 38-53).

GitHub Projects Adapter Configuration

Set type: github-projects and specify your organization (or username) and the numeric project ID. Authentication is handled entirely through the GitHub CLI.

pmTool:
  type: github-projects
  config:
    org: your-github-username-or-org
    project_number: 42

Ensure you have authenticated via:

gh auth login

The factory logs the selected adapter type and creates a GitHubProjectsAdapter instance with the supplied org and project_number (factory.js lines 76-86). No API token is stored in the configuration file; the adapter invokes gh commands directly.

Local Fallback Mode

If you omit .aiox-pm-config.yaml or set type: local, AIOX uses the LocalAdapter, which records stories only in the local filesystem without external API calls.

Using the Adapter in Your Code

Once configured, import the factory utilities and call adapter methods:

const { getPMAdapter, isPMToolConfigured } = require('./.aiox-core/infrastructure/scripts/pm-adapter-factory');

async function syncStory(storyPath) {
  if (!isPMToolConfigured()) {
    console.log('Running in local-only mode – no external PM sync.');
    return;
  }

  const adapter = getPMAdapter();
  const result = await adapter.syncStory(storyPath);
  
  if (result.success) {
    console.log(`Story synced! URL: ${result.url}`);
  } else {
    console.error(`Sync failed: ${result.error}`);
  }
}

To pull status updates from your PM tool:

const { getPMAdapter } = require('./.aiox-core/infrastructure/scripts/pm-adapter-factory');

(async () => {
  const adapter = getPMAdapter();
  const { success, updates, error } = await adapter.pullStory('AIOX-123');
  
  if (success) {
    console.log('Current status:', updates.status);
  } else {
    console.error('Failed to pull:', error);
  }
})();

Linear Integration Status

AIOX currently ships adapters for Jira, GitHub Projects, ClickUp, and the Local fallback. The term Linear in AIOX documentation refers to a workflow style, not a specific adapter implementation. To integrate with Linear, you must implement a custom adapter that extends the abstract PMAdapter class and register it in pm-adapter-factory.js. Until such an adapter exists, use Jira or GitHub Projects as the supported alternatives.

Summary

• Create .aiox-pm-config.yaml at your project root to enable external PM integration.
• Set pmTool.type to jira (requiring JIRA_API_TOKEN and JIRA_EMAIL) or github-projects (requiring gh auth login).
• Import getPMAdapter() from .aiox-core/infrastructure/scripts/pm-adapter-factory.js to obtain a singleton instance.
• Use syncStory(), pullStory(), updateStatus(), and createStory() to manage story lifecycle.
• Linear is not supported natively; implement a custom adapter following the PMAdapter contract if needed.

Frequently Asked Questions

Does AIOX support Linear integration natively?

No, AIOX does not include a native Linear adapter. The repository currently provides adapters for Jira, GitHub Projects, ClickUp, and local file storage only. To use Linear, you must create a custom adapter class that implements the syncStory(), pullStory(), updateStatus(), and createStory() methods defined in the abstract PMAdapter base class, then register it in the factory.

What authentication is required for the Jira adapter?

The Jira adapter requires two environment variables: JIRA_EMAIL containing your Atlassian account email, and JIRA_API_TOKEN containing a personal API token generated from your Atlassian account settings. These are read at runtime by the adapter constructor in jira-adapter.js and are never stored in the YAML configuration file.

Can I run AIOX without an external PM tool?

Yes. If the .aiox-pm-config.yaml file is missing, malformed, or explicitly sets type: local, the PM Adapter Factory automatically falls back to the LocalAdapter. This allows AIOX to create, update, and manage stories entirely within local YAML files without requiring internet connectivity or external API credentials.

How do I verify my PM adapter configuration is working?

Call isPMToolConfigured() from the factory before attempting operations; it returns true only when a valid external adapter is active. Then invoke adapter.syncStory() with a test story file and check the returned object’s success property. If false, the error property contains details from the underlying API (Jira REST errors or GitHub CLI exit codes).

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}