Connect your tools.

Ordel connects to Azure DevOps, Jira, Linear, GitHub and Slack from Admin > Integrations. Each tool needs a token or URL that you create in that tool first. This guide walks through each one, with the smallest set of permissions that lets Ordel import work items and file defects back.

Before you start

• Every token is shown once. Azure DevOps, Linear and GitHub (and Atlassian for Jira) display a token only when you create it. Copy it somewhere safe before you paste it into Ordel; if you lose it, make a new one.
• Use a dedicated account where you can. A token acts as the account that made it, and anything Ordel files shows that account. A service or test account is safer than a personal admin token.
• Webhooks need Ordel to be reachable from the internet. Jira, GitHub, Linear and Azure DevOps push changes to Ordel only if they can call it. On a local or private install, use Sync Now or schedule syncs instead and leave the webhook secret blank.
• Where to start in Ordel. Admin > Integrations lists the five integrations. Each card opens a "Connect" dialog. Once saved, bring requirements in through Requirements > Connect Source (pick the integration, workspace, item types and statuses, review), then Sync Now.

<!-- providers:begin (identical in the public guide and the manual page; a test keeps them in step) -->

Azure DevOps

1. Sign in at dev.azure.com and open your organization.
2. Open User settings (top right), then Personal access tokens, then New Token.
3. Name the token, pick the organization, and set an expiry.
4. Under Scopes choose Custom defined. Tick Work Items: Read & write (read to import, write so Ordel can file defects back). Click Show all scopes and tick Project & Team: Read, because Ordel lists your projects while you connect.
5. Create the token and copy it now: Azure DevOps shows it once.
6. In Ordel, open Admin > Integrations, Connect Azure DevOps, and fill in:
   • Organization: the organization name only, for example kestrel-ai, not the URL.
   • Personal Access Token: the token.
   • Shared Secret: leave blank unless you set up a service hook (see the webhook note at the top of this page).

Jira

Jira Cloud only: Ordel connects with an Atlassian account email and an API token.

1. Go to id.atlassian.com, then Security, then API tokens, then Create API token. Name it and copy the token: it is shown once.
2. In Ordel, open Admin > Integrations, Connect Jira, and fill in:
   • Jira Base URL: https://<your-site>.atlassian.net.
   • Jira Project Key: the key of the project defects are filed to, for example ODOO. You can leave it blank to only import, but filing a defect to Jira needs it.
   • Email: the email of the Atlassian account that owns the token.
   • API Token: the token.
   • Webhook Secret: leave blank unless you set up a webhook (see the webhook note at the top of this page).

The token acts as the account that created it, so every issue Ordel files shows that account as the reporter. Create the token under a dedicated account if you do not want that to be a person.

Linear

1. In Linear, open Settings, then Account, then Security & access, then Personal API keys, then New API key.
2. Choose "Only select permissions" and tick Read, Create issues and Create comments. Choose the teams Ordel may import from. Ordel does not need Linear's Admin permission to import or file issues; Linear asks for it only to create a webhook.
3. Create the key and copy it now: Linear shows it once.
4. In Ordel, open Admin > Integrations, Connect Linear, and fill in:
   • API Key: the key.
   • Webhook Signing Secret: leave blank unless you set up a webhook (see the webhook note at the top of this page).

GitHub

Fine-grained personal access tokens work, and are what GitHub recommends; you do not need a classic token with the broad repo scope.

1. On github.com open Settings, then Developer settings, then Personal access tokens, then Fine-grained tokens, then Generate new token.
2. Resource owner: the account or organization that owns the repository. If it is an organization, an owner must approve the token before it works (it shows as Pending until then). A repository on a personal account needs no approval.
3. Repository access: Only select repositories, and pick the one you want.
4. Permissions: Contents Read and write, Issues Read and write, Webhooks Read and write, Pull requests Read, Actions Read. GitHub adds Metadata Read by itself.
5. Generate the token and copy it now: GitHub shows it once.
6. In Ordel, open Admin > Integrations, Connect GitHub, and fill in:
   • Personal Access Token: the token.
   • Webhook Secret: leave blank unless you set up a webhook (see the webhook note at the top of this page).

Slack

Slack is for notifications going out of Ordel; nothing is imported from it.

1. Go to api.slack.com/apps, choose Create New App, then From scratch (or Blank app), name it and pick your workspace.
2. Under OAuth & Permissions add the bot scope incoming-webhook and nothing else. Skip Events.
3. Install the app to the workspace. On the "Allow the app to access Slack" screen pick the channel notifications should go to, then Allow.
4. Open Features, then Incoming Webhooks, and copy the URL from the "Webhook URL" row of the table. It starts with https://hooks.slack.com/services/.
5. In Ordel, open Admin > Integrations, Connect Slack, paste it into Incoming Webhook URL and save.

Do not use the app's Basic Information page: its Client ID, Client Secret, Signing Secret and Verification Token are not what Ordel needs, though it is the page you land on first after creating the app.

<!-- providers:end -->

After you connect

Open Requirements > Connect Source to choose what to import, then Sync Now. Defects you file from a failed run go back to the connected tracker. See Jira for what the tracker integrations do once connected.