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

> Easily configure the PM adapter for Jira or GitHub integration in AIOX. Create a .aiox-pm-config.yaml file and import getPMAdapter() to sync your stories effortlessly.

- Repository: [SynkraAI/aiox-core](https://github.com/synkraai/aiox-core)
- Tags: how-to-guide
- Published: 2026-03-15

---

**Configure the PM adapter by creating a [`.aiox-pm-config.yaml`](https://github.com/SynkraAI/aiox-core/blob/main/.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`](https://github.com/SynkraAI/aiox-core/blob/main/.aiox-core/infrastructure/scripts/pm-adapter-factory.js)) detects the presence of [`.aiox-pm-config.yaml`](https://github.com/SynkraAI/aiox-core/blob/main/.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`](https://github.com/SynkraAI/aiox-core/blob/main/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`](https://github.com/SynkraAI/aiox-core/blob/main/.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`](https://github.com/SynkraAI/aiox-core/blob/main/.aiox-core/infrastructure/integrations/pm-adapters/github-adapter.js)) uses the GitHub CLI (`gh`) and GraphQL API v2.

## Configuring the [`.aiox-pm-config.yaml`](https://github.com/SynkraAI/aiox-core/blob/main/.aiox-pm-config.yaml) File

Create this file at the same level as your [`package.json`](https://github.com/SynkraAI/aiox-core/blob/main/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.

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

```

Before running AIOX, export these environment variables:

```bash
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`](https://github.com/SynkraAI/aiox-core/blob/main/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.

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

```

Ensure you have authenticated via:

```bash
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`](https://github.com/SynkraAI/aiox-core/blob/main/.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:

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

```javascript
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`](https://github.com/SynkraAI/aiox-core/blob/main/pm-adapter-factory.js). Until such an adapter exists, use Jira or GitHub Projects as the supported alternatives.

## Summary

- Create [`.aiox-pm-config.yaml`](https://github.com/SynkraAI/aiox-core/blob/main/.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`](https://github.com/SynkraAI/aiox-core/blob/main/.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`](https://github.com/SynkraAI/aiox-core/blob/main/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`](https://github.com/SynkraAI/aiox-core/blob/main/.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).