CI with org keys
Use an organization API key (pko_*) when the work isn’t tied to a specific person — CI/CD, scheduled jobs, agent fleets, anything that should keep working when an engineer leaves. Org keys carry org identity (not a user seat) and can target any project in the organization (or a project allowlist).
Personal token or org key?
Start with a personal token for your own work; reach for an org key when automation outgrows it.
Personal token (plt_*) | Org key (pko_*) | |
|---|---|---|
| Bound to | A user | The organization (service principal) |
| Default project | Optional, pinned per user | None — passed explicitly per call |
| Project scope | Projects you can access | All org projects, or an allowlist |
| Best for | Your own agent in your editor | CI, scheduled jobs, multi-project fleets |
| Revocation | Per user, via Settings | Org-wide, via Settings → API Keys |
For the personal-token, switch-projects-mid-session workflow, see Work across two projects.
Generate the key
- Open Settings → Authentication → API Keys in the dashboard.
- Click Generate Org Key.
- Pick:
- Description — what it’s for (“GitHub Actions deploy”, “Production cron”).
- Expiration — never, 30/90/180/365 days. CI keys typically rotate quarterly.
- Project scope — All projects (full org), or Restrict to specific projects with a checklist.
- Copy the
pko_…value once. It’s hashed at rest — you cannot see it again.
The dashboard table shows last-used timestamp and lets you revoke the key the moment something looks off.
Install in CI
The CLI accepts the key non-interactively:
PLENAR_TOKEN=pko_… plenar connect --key pko_…In a GitHub Actions step:
- name: Connect Plenar
env:
PLENAR_TOKEN: ${{ secrets.PLENAR_ORG_KEY }}
run: plenar connect --key "$PLENAR_TOKEN"This skips the browser OAuth flow, validates the token, writes .mcp.json, and configures the workflow files. The key never appears in logs — the CLI redacts it to pko_… in any error output.
Use in scripts and tools
Any MCP call from CI must include project_id — org keys deliberately have no default project (so a misconfigured pipeline can’t silently target the wrong one). Two patterns:
1. Explicit per-script. Set PLENAR_PROJECT_ID in the workflow env and pass it to every call.
2. Single-project allowlist. If the key is restricted to one project in its allowlist, the CLI auto-resolves it as the default. plenar status shows the resolved scope:
Connected to Plenar (org-key mode)
Org: Acme
Created: alice.chen@acme.com
Scope: 1 project(s), allowlist enforced
• [PLEN-DEMO] Demo AppFor scripts that need to query state in machine-readable form, every CI-targeted command supports --json:
plenar status --json | jq -r '.organization.name'Stdout carries JSON, stderr carries human-readable warnings — pipes don’t get polluted.
Rotate
- Open Settings → Authentication → API Keys.
- Generate Org Key with the same description and scope.
- Update the secret in your CI provider (
PLENAR_ORG_KEY). - Trigger one CI run to confirm the new key works (
plenar statusis the cheapest probe). - Revoke the old key from the dashboard. Last-used timestamp helps you confirm nothing else is using it first.
Revocation is instant — the next request from a revoked key fails with HTTP 401.
Failure behavior
| Situation | What happens |
|---|---|
PLENAR_TOKEN unset, signal / hook invoked | Warns to stderr, exits 0. Missing telemetry never breaks a CI job. |
| Token present but invalid/revoked | Stderr error, exits 2 (auth error). CI job fails visibly so you fix it. |
Network timeout (default 10s, override PLENAR_TIMEOUT_MS) | Stderr error, returns control. Hanging CLI never wedges the runner. |
| Rate limited | Retries once, then warns and continues. Heavy bursts are absorbed gracefully. |
These guarantees apply to every CI-targeted subcommand: signal *, hook *, run, connect --key, status, whoami.
Common questions
Why does every call need a project ID? Org keys carry no default project on purpose — so a misconfigured pipeline can’t silently write to the wrong one. Set PLENAR_PROJECT_ID, or restrict the key to a single project so the CLI resolves it automatically.
Will missing telemetry break my CI job? No. When the token is unset, signal and hook commands warn to stderr and exit 0 — telemetry is fire-and-forget and never fails a build.
How often should I rotate? CI keys typically rotate quarterly. Generate the replacement, update the CI secret, confirm one run, then revoke the old key — its last-used timestamp tells you nothing else depends on it.
What happens the instant I revoke a key? The next request from it fails with HTTP 401. Revocation is immediate, org-wide, and not reversible — generate a fresh key to restore access.
What to do next
- Work across two projects — the personal-token workflow for your own sessions.
- CLI reference — every
plenarcommand and flag, includingconnect --key. - Integrations — connect external systems that feed the plan.