Start here

Connect Jira

Connecting Jira lets Winston look up your projects and issues and report on them. You create an API token in your Atlassian account, then give Winston the token, your Jira site and the email you sign in with. This page shows each screen.

Before you start

You need to be an Owner or Admin in Winston.
This is for Jira Cloud, the sites at your-site.atlassian.net.
Decide which Atlassian account Winston should act as. The token carries that account's permissions: Winston sees the projects and issues that account can see, and nothing more. A shared account such as winston@yourcompany.com often works best.

The connection belongs to the Winston workspace, not only to you. Anyone in the workspace who asks Winston can have it read the projects the account can open. The token allows whatever that account can do in Jira, so Winston still asks before it changes anything; see Review and approve.

1. Create an API token at Atlassian

Sign in as the account Winston should use and go to id.atlassian.com/manage-profile/security/api-tokens (Atlassian account → Security → API tokens). Choose Create API token. Winston has been tested with this kind of token. A token from Create API token with scopes is meant for Atlassian's API gateway rather than your site's own address, so Winston may not be able to use it.

Name: something you'll recognize, such as Winston.
Expires on: Atlassian suggests a date a week away. Pick a later one, up to a year. When the token expires, Winston loses access until you give it a new one.

Atlassian's Create an API token dialog with the name Winston and the Expires on date outlined — Name the token and choose how long it lasts. The default is only a week.

Choose Create. Atlassian shows the token once. Choose Copy and go straight on to the next step.

2. Connect it in Winston

In Winston, open Settings → Connections, find the Jira card (under Project Management, or type "Jira" into the search box) and choose Connect.

The Connections screen in Winston searched for Jira, with the Jira card's Connect button outlined — Settings → Connections. Find Jira and choose Connect.

Fill in all three fields, then choose Connect:

API Token: paste the token. Winston shows it only as dots.
Email: the email of the Atlassian account that made the token.
Jira Domain: your site's address without https://, for example your-site.atlassian.net. It's the start of any Jira link from your site.

Winston's Jira dialog, badged http_basic, with the API Token shown as dots, an email address and the Jira Domain your-site.atlassian.net filled in — The token, the account's email and your Jira site. All three are required.

3. Check it is connected

Winston checks the details with Jira and confirms with Jira is connected. Choose Done.

Winston's dialog headed Jira is connected, saying Winston can now use your Jira account, with a Done button — Winston confirms the connection. Choose Done.

The Jira card on the Connections screen with a green Connected badge, a pencil icon and a plug icon — The Jira card after connecting. The pencil changes the details; the plug disconnects.

Then ask Winston a small read-only question in Chat, for example "Which Jira site and account are you connected as, and what projects can you see?" Winston names the site and account and lists the projects. If it names the wrong site, correct the Jira Domain with the pencil.

Change the token, email or site

Choose the pencil on the Jira card. Fill in only what changes, such as a new token after the old one expired, and choose Save Changes. A field left blank keeps its current value.

Winston's Update Jira dialog with API Token showing (unchanged), the email and the Jira Domain, and Cancel and Save Changes buttons — The pencil opens Update Jira. Leave the token blank to keep the current one.

Disconnect

To stop Winston using Jira, choose the plug icon on the Jira card and confirm Disconnect. This applies to the whole workspace.

Disconnecting removes the token from Winston but does not cancel it at Atlassian. To make sure it can no longer be used anywhere, revoke it on the same API tokens page at Atlassian as well.

If something does not work

What you see	What to do
Winston says Jira refused the sign-in (401 or Unauthorized)	Check that Email is the account that made the token, and that the token has not expired or been revoked. Make a new token if needed and paste it in with the pencil.
Winston says it can't find the site	Jira Domain should be just the host, such as your-site.atlassian.net, with no https:// and nothing after .net.
It worked, then stopped about a week later	The token expired. Create a new one with a later expiry date and paste it in with the pencil.
A project you expected is missing	The account cannot see that project. Give it access in Jira, or connect with an account that already has it.

For other connections, see Connect your tools. Anything else, see Troubleshooting or contact Support from the dashboard.