# Set up GUIJam for Jira

> Install the GUIJam for Jira app, create a Jira space, add GUIJam to a new or existing frontend project, and pair it with Jira using one code.

## Install the Jira app

A Jira site admin opens the [GUIJam for Jira installation link](https://developer.atlassian.com/console/install/9f6e7bd4-561f-42c1-967c-534533ca84fd?signature=AYABeNHZxmIIzqskV6bj6ZDb2BwAAAADAAdhd3Mta21zAEthcm46YXdzOmttczp1cy13ZXN0LTI6NzA5NTg3ODM1MjQzOmtleS83MDVlZDY3MC1mNTdjLTQxYjUtOWY5Yi1lM2YyZGNjMTQ2ZTcAuAECAQB4CxqLTo9l4lqXuFjNim1xJM%2Bp%2F3TVP9xHS2BrU5DRRucB9X7SgA05cnObTkvhYN1xbQAAAH4wfAYJKoZIhvcNAQcGoG8wbQIBADBoBgkqhkiG9w0BBwEwHgYJYIZIAWUDBAEuMBEEDNEhzAe7TPWDBVqk6wIBEIA7keQSd6CapbYmtUGdkeKKsGD9awYJ3ooCpMpwMF2EDUNbpBp%2F9PeiHpLYzLpKRCnH1ToDtNvaJyOei0kAB2F3cy1rbXMAS2Fybjphd3M6a21zOmV1LXdlc3QtMTo3MDk1ODc4MzUyNDM6a2V5LzQ2MzBjZTZiLTAwYzMtNGRlMi04NzdiLTYyN2UyMDYwZTVjYwC4AQICAHi9bVMAkme4qVQX1fQHo6ePw3H40A7cGfz7yrmSfBWMXgEaeJ%2BkdCobmSDv47DLtIySAAAAfjB8BgkqhkiG9w0BBwagbzBtAgEAMGgGCSqGSIb3DQEHATAeBglghkgBZQMEAS4wEQQMGEExVBpjK5bbUYmTAgEQgDvy5cWJv19sweBbrSFr5C3xdwywv%2BBv20pRtihL1aMr7o8uQnVvR9vasue1xGfDidyWyh8RzUzmiGXFBQAHYXdzLWttcwBLYXJuOmF3czprbXM6dXMtZWFzdC0xOjcwOTU4NzgzNTI0MzprZXkvNmMxMjBiYTAtNGNkNS00OTg1LWI4MmUtNDBhMDQ5NTJjYzU3ALgBAgIAeDYASx0XCjkny4iLV6vz%2BKtEGSGT6kdt0QRpkn6D%2FlVEAWqyfoA4bYp55SbOGUdCdOkAAAB%2BMHwGCSqGSIb3DQEHBqBvMG0CAQAwaAYJKoZIhvcNAQcBMB4GCWCGSAFlAwQBLjARBAwmXimEV%2FsYgm0GihwCARCAO2yT52i7N%2B%2BDNBN%2F2F87pJutoitrvTBVazhVeMuRbv%2BmP8xV9sDbTccsGcHKl%2BfdohjSFjjtL%2BQGx983AgAAAAAMAAAQAAAAAAAAAAAAAAAAAKlWUN4JXPX85evX3RKxCVz%2F%2F%2F%2F%2FAAAAAQAAAAAAAAAAAAAAAQAAADLbFlcEhVS0TGlPnle4N%2FWi6ZPs4%2FxogfU6%2BLKHwDp0vbTyhpPRk4JYHRWIvoxpoJGa%2F4o%2Fn8CSg1cuvGh0MKv91WQ%3D\&product=jira), chooses the site, for example `yourteam.atlassian.net`, and installs it. The app asks for:

| Permission                    | Why                                                                                                  |
| ----------------------------- | ---------------------------------------------------------------------------------------------------- |
| Read and write Jira work      | Read tickets and their images; post comments, screenshots and status moves; create reported tickets. |
| Read users and permissions    | Show who applied a change, and check each person's own Jira permissions before every read and write. |
| App storage                   | Keep pairing records (as hashes), results and rate limits inside Jira.                               |
| Images from `*.atlassian.net` | Show the ticket's own before and after screenshots in the GUIJam panel.                              |

## Create a Jira space

Jira now calls projects **Spaces**. Use a software space, since UI tickets belong next to development work.

1. Open **Jira**, not Confluence: use the grid icon at the top left, or go to `yourteam.atlassian.net/jira`.
2. In the sidebar, hover **Spaces** and click **+**. Choose **Software development**, then **Kanban**, then a **team-managed** space.
3. Name it, for example **Web**, and set the key to `WEB`. Ticket keys start with it: `WEB-1`, `WEB-2`.

A brand-new space can say you don't have permission to create work in it for a minute. Wait, refresh, and use work type **Task**.

## Create a frontend project

Skip this if you already have an app. Otherwise, start one with your framework's own starter:

| Framework    | Command                                                 |
| ------------ | ------------------------------------------------------- |
| React + Vite | `npm create vite@latest my-shop -- --template react-ts` |
| Vue + Vite   | `npm create vite@latest my-shop -- --template vue-ts`   |
| Solid + Vite | `npm create vite@latest my-shop -- --template solid-ts` |
| SvelteKit    | `npx sv create my-shop`                                 |
| Astro        | `npm create astro@latest my-shop`                       |
| Next.js      | `npx create-next-app@latest my-shop`                    |
| Nuxt         | `npx nuxi@latest init my-shop`                          |
| React Router | `npx create-react-router@latest my-shop`                |

```bash
cd my-shop
npm install
```

## Install GUIJam and connect Jira

In your app's folder:

```bash
npx guijam@latest init
```

`init` detects your framework, adds `guijam`, wires your config and helps you pick an AI coding CLI. Its last step is optional:

```txt
Link UI tickets to your changes: GUIJam posts before/after screenshots and the diff to the ticket.
? Connect Jira?  No / Yes
```

Choose **Yes** and it asks for a pairing code. Get one from Jira:

1. Create any ticket with **+ Create**, work type **Task**, and open it.
2. Under the ticket's title, click the **GUIJam** button. If it isn't there, look under **Apps** or **•••** in that row.
3. If Jira asks, click **Allow access**. The app reads which projects you can use, as you.
4. In the GUIJam panel, click **Pair GUIJam**. A green box shows a command with a code that starts with `gjp_`. It's shown once.
5. Paste the code into `init`, or run the command in your app's folder:

```bash
npx guijam jira pair gjp_eyJ2IjoxLCJ1cmwiOi...
```

```txt
Paired with yourteam.atlassian.net as Ana Cruz. GUIJam can now link your changes to Jira tickets.
```

> **The code is a credential**
>
> Anyone with it can act as you through GUIJam, within your Jira permissions. Don't paste it into chats or tickets. If it leaks, click **Revoke** in the panel and pair again.

## Check the connection

```bash
npx guijam jira status   # the paired sites
npx guijam jira test     # Connected to yourteam.atlassian.net as Ana Cruz. 3 open tickets are assigned to you.
npx guijam doctor        # the whole setup, including Jira
```

Then start your dev server as usual and open the app. The GUIJam toolbar sits at the bottom right.

Next: [Work Jira tickets in GUIJam](https://guijam.francistinao.com/docs/jira/working-tickets).
