Credentials

Orion works without Jira or Slack. Slack adds a channel per project and the notification stream; Jira adds a project per idea and the decomposed work tree.

Store and check credentials

orion config          # asks for everything, stores it, secrets never echoed
orion config show     # what is set and where it came from, masked
orion doctor          # proves the credentials actually work

orion config writes ~/.orion/config.env, outside any repository, at mode 0600; config show says how to fix the mode if it widens. Orion reads the file itself, so cron and launchd jobs see the credentials, which an export in ~/.zshrc would not give them. An exported environment variable overrides the file. The binary never passes the tokens to an agent (The sandbox covers what agents can read, and Safety and limits what leaves your machine).

orion doctor reports a missing integration as degraded capability. With tracker.enabled or slack.enabled set in orion.json, a broken credential blocks instead.

Slack: a bot token, not a webhook

You need a bot token (xoxb-...). An incoming webhook is bound to one channel and cannot create channels.

Before you start

If your workspace needs an admin to approve apps, ask before building one, or it sits pending. Slack → your workspace name → Tools & settings → Manage apps → App management settings shows the policy.

1. Create the app from a manifest

Go to https://api.slack.com/apps → Create New App → From a manifest → pick your workspace → paste this:

display_information:
  name: Orion
  description: AI-native SDLC orchestrator. Creates a channel per project and reports there.
  background_color: "#1a1a2e"
features:
  bot_user:
    display_name: Orionbot
    always_online: false
oauth_config:
  scopes:
    bot:
      - channels:manage
      - channels:read
      - channels:join
      - groups:write
      - groups:read
      - chat:write
      - chat:write.public
      - users:read
      - reactions:read
      - channels:history
      - groups:history
settings:
  org_deploy_enabled: false
  socket_mode_enabled: false
  token_rotation_enabled: false

What each scope is for:

Scope	Needed for
channels:manage	creating public channels
groups:write	creating private channels (the default)
channels:read / groups:read	finding an existing channel by name, so a re-run attaches instead of failing
channels:join	joining a reused public channel. A bot is a member of a channel it created, but not of one it merely found, and setting the topic requires membership
chat:write	posting anything at all
chat:write.public	posting to a public channel without joining it first
users:read	inviting people to a channel Orion creates
reactions:read	reading an approval given as an emoji reaction
channels:history / groups:history	reading an approval typed as a thread reply, in a public / private channel

If you only ever want private channels, drop channels:manage and channels:read. If only public, drop the groups:* scopes and set "private": false in orion.json.

Leave token_rotation_enabled off: Orion has no refresh loop, so a rotating token stops working roughly twelve hours later. Socket mode stays off because Orion receives no events.

2. Install it and copy the token

Install App in the left sidebar → Install to Workspace → review the permissions → Allow. Then, under Install App or OAuth & Permissions, copy the Bot User OAuth Token. It starts xoxb-.

orion config --only ORION_SLACK_TOKEN

The prompt does not echo the token, and Orion never logs it.

3. Turn it on and verify

orion plan turns Slack on for the projects it creates. For a repository you adopted, add this to its orion.json:

"slack": { "enabled": true, "create_channel_per_project": true,
           "channel_prefix": "orion-", "private": true }

orion doctor

The slack line names the workspace:

[OK  ] slack    Your Workspace as orionbot (workspace T01ABCDEF)

Check it is the workspace you meant: a token for the wrong one authenticates and posts where nobody reads. orion slack test [KEY] sends a real message and reports what breaks.

Slack scopes, channels and invites

• Adding a scope needs a reinstall (Orion's missing_scope error says so).
• Channels are private by default, and the bot is the only member of one it creates. Without slack.invite_users in orion.json, Orion creates a channel you cannot see and reports success. Put your Slack member ID (U...) there, from your profile, More → Copy member ID. The slack audience doctor check fails when a channel has only the bot.
• For an existing private channel, run /invite @Orion in it once. Public channels are joined automatically.
• A bot cannot delete channels; archive a finished project's channel.
• Rename the bot under App Home → Your App's Presence in Slack → Display Name (Bot Name), with no reinstall.

Slack and approvals covers what Orion posts and how approvals work.

Jira: an API token

1. Create the token

Go to https://id.atlassian.com/manage-profile/security/api-tokens → Create API token → name it orion → copy it now, because Atlassian shows it once.

2. Give it to Orion

orion config --only ORION_JIRA_URL,ORION_JIRA_EMAIL,ORION_JIRA_TOKEN

Use the email of the account that created the token. Jira answers HTTP 401 alike for a revoked token, a mismatched email and a truncated token, so on failure re-enter both.

Environment variables also work and override the file:

export ORION_JIRA_URL='https://yourorg.atlassian.net'   # no trailing slash
export ORION_JIRA_EMAIL='you@example.com'
export ORION_JIRA_TOKEN='...'

The stale export

An export beats config.env for the life of that terminal, so after you fix the token with orion config, doctor still fails there and passes in a new tab. Doctor names the source (authentication failed (credentials from: environment)) and prints the unset line to run.

3. Verify

orion doctor

It prints one of three lines:

[OK  ] jira   authenticated as Your Name, can create projects (via CREATE_PROJECT)
[WARN] jira   cannot create projects
[WARN] jira   permission undetermined

"Undetermined" means the deployment restricts the permissions endpoint. Orion attempts creation and falls back cleanly.

If you cannot create Jira projects

Creating a Jira project per idea, the default, needs the Create team-managed projects global permission. Without it, bind to an existing project:

"tracker": { "provider": "jira", "project_key": "PROJ",
             "create_project_per_idea": false,
             "confirm_tree_before_create": true }

Orion then creates its issues inside PROJ and never makes a project.

With per-idea projects, keys are unique per instance and at most 10 characters: Orion takes the name's word initials (claim-status-self-service → CSSS) and appends a digit on a collision. A non-admin cannot delete a Jira project, so for many small ideas bind to one key. Either way the work tree is previewed and one yes creates it; only orion plan KEY --yes run off a terminal, as the web dashboard's Plan button does after you confirm, answers for you.

Notifications without a Slack app

For outbound notifications only, export a Slack incoming webhook:

export ORION_NOTIFY_WEBHOOK='https://hooks.slack.com/services/...'

Orion posts JSON with a Slack-compatible text field, so no adapter is needed. The webhook gets stage failures, a tripped breaker, a quota wall with its resume time, and orion report --notify, but cannot create channels or read approvals. ORION_NOTIFY_COMMAND runs a command of your choice instead. Desktop notifications fire on macOS and Windows regardless.