# Atlassian Operating Runbook

# Cold Bore Ballistics, LLC

**Last updated:** 2026-06-10
**Audience:** Anyone operating the Atlassian instance day-to-day — written assuming **no
prior Atlassian experience.**
**Companion docs:** `Atlassian_Architecture_Reference.md` (what exists) ·
`Atlassian_Rebuild_Guide.md` (rebuild from scratch).

> This runbook covers recurring tasks. Each procedure is self-contained and assumes you
> are signed in as `admin@coldboreballisticsllc.com`. Where a task can be done two ways
> (web UI vs. REST API), the UI steps are given first because they need no setup.

---

## Table of Contents

1. [Signing in and orientation](#1-signing-in-and-orientation)
2. [Add a new user](#2-add-a-new-user)
3. [File and triage a support ticket (ESUP)](#3-file-and-triage-a-support-ticket-esup)
4. [Configure JSM portal groups (manual)](#4-configure-jsm-portal-groups-manual)
5. [Create and work an issue in DOPE or CBB](#5-create-and-work-an-issue-in-dope-or-cbb)
6. [Close or resolve an issue](#6-close-or-resolve-an-issue)
7. [Start work: create a branch linked to an issue](#7-start-work-create-a-branch-linked-to-an-issue)
8. [Run a release in Jira](#8-run-a-release-in-jira)
9. [Edit a Confluence page](#9-edit-a-confluence-page)
10. [Set the External Visibility default (one-time)](#10-set-the-external-visibility-default-one-time)
11. [Clean up default resolutions (one-time)](#11-clean-up-default-resolutions-one-time)
12. [API access for scripts](#12-api-access-for-scripts)
13. [Configure ESUP → DOPE automation rules](#13-configure-esup--dope-automation-rules)

---

## 1. Signing in and orientation

1. Go to `https://coldboreballisticsllc.atlassian.net`.
2. Sign in with `admin@coldboreballisticsllc.com`.
3. The **app switcher** is the grid icon (top-left, nine dots). It moves you between
   Jira, Jira Service Management, and Confluence.
4. Organization-level administration (users, billing, products) lives at a separate
   address: `https://admin.atlassian.com`.

---

## 2. Add a new user

A user must be invited to the site, then placed in the right group(s). Group membership is
how access is controlled (see Architecture Reference §3).

### Via the web UI

1. Go to `https://admin.atlassian.com` and select the organization.
2. Left sidebar → **Directory → Users → Invite users**.
3. Enter the person's email. For a CBB team member, the email must be on the
   `coldboreballisticsllc.com` domain.
4. Grant product access: **Jira**, **Jira Service Management** (only if they are a support
   agent), and/or **Confluence**.
5. Send the invite. The person receives an email and must accept before they appear as
   active.
6. After they accept, add them to groups: **Directory → Groups →** pick the group
   (`jira-users`, etc.) **→ Add members**.

| Who they are | Groups to add |
|---|---|
| Developer / team member | `jira-users` |
| Support agent | `jira-users` + `jsm-agents` |
| External / limited contributor | `jira-reporters` |
| Another administrator | `jira-admins` |

### Via script (batch)

For onboarding several people at once, `cbb-utils/atlassian/add_user.py` invites and
assigns groups from a CSV or JSON file. See that directory's README. Use the UI for
one-off additions; use the script only when adding many users at once.

> **Seat limits:** Free plan allows 10 Jira users, 3 JSM agents, 10 Confluence users.
> Adding an 11th Jira user requires a paid plan.

---

## 3. File and triage a support ticket (ESUP)

### How a ticket arrives

External and internal reporters submit through the **customer portal**:
`https://coldboreballisticsllc.atlassian.net/servicedesk/customer/portal/<id>`
(the portal must have its groups configured — see §4). Each submission becomes an ESUP
issue.

### Triaging a ticket (as the agent)

> **Automation is active.** Bug and Feature Request submissions from the portal are
> automatically converted to DOPE issues and closed in ESUP within seconds of submission
> (see §11). You should rarely need to triage these manually. The steps below apply to
> edge cases: tickets that arrive outside automation (e.g., manually created in ESUP), or
> tickets that need clarification before the DOPE issue is useful.

1. App switcher → **Jira Service Management → ESUP → Queues**.
2. Open the ticket. The comment on automated tickets already shows the DOPE key — no
   action needed unless you want to add context to the DOPE issue.
3. **If a ticket needs clarification first:**
   - Set status to **Waiting for Reporter** and add a comment asking for details.
   - The reporter is notified by email.
   - Once clarified, add the information to the linked DOPE issue and resume work there.
4. **If a ticket arrived outside automation** (e.g., manually filed):
   - Use **Link issue** → create a linked issue in **DOPE** (product) or **CBB**
     (operations). Set the ESUP ticket to **In Progress**.
   - When the linked issue is resolved, set the ESUP ticket to **Resolved** and add a
     short resolution note. The reporter is notified.

---

## 4. Configure JSM portal groups (manual)

The customer portal shows "There's nothing in this portal yet" until **portal groups**
exist with request types assigned. The Free-plan API blocks creating them, so this is a
one-time manual task. The Atlassian UI changed in 2025–2026; the path below reflects the
current UI.

1. Open the **ESUP** project.
2. **Project settings** (left sidebar) → **Channels & self service** (it may appear as
   **Channels** with a sub-menu) → **Portal** → **Portal Groups** tab.
3. Click **Create group**, name it **Report a Bug**.
4. Expand the group → **+ Add request form** → add all seven Bug request types.
5. Repeat: create **Request a Feature** (add the 4 Feature Request types) and **Other**
   (add Hardware Validation Task + Admin / Legal / Business).
6. You must create **at least two groups** before any become visible on the portal —
   create all three before testing.

Request-type-to-group assignment:

| Portal group | Request types |
|---|---|
| Report a Bug | Bug — Crash or Freeze · Calculation/Accuracy · UI/Display · Printer/Label · Sensor/BLE Connectivity · Data/Session File · Performance |
| Request a Feature | New Feature · Improvement · Ammo Database · Hardware Support |
| Other | Hardware Validation Task · Admin / Legal / Business |

---

## 5. Create and work an issue in DOPE or CBB

1. App switcher → **Jira**. Pick **ScopeDOPE (DOPE)** for product work or
   **Cold Bore Ballistics — Operations (CBB)** for company work.
2. Click **Create** (top bar).
3. Fill in: **Issue type** (Task/Story/Bug/Improvement/Epic), **Summary**, **Description**.
4. Set **Component** (e.g. Ballistics Engine), **Priority**, and **Fix version** if it
   targets a release.
5. **Set the Repository field** — choose the repo(s) the work touches. For an engine change
   that spans `scopedope-android` and `scopedope-shared`, select both. (This field does
   not appear for `dope-format` work — that lives in GitHub Issues, never Jira.)
6. Create. Drag the card across the board columns as work progresses
   (To Do → In Progress → In Review → Done).

> **Valid priorities in Jira Cloud are `Highest / High / Medium / Low / Lowest`.**
> "Blocker" is a Jira Server term and does not exist here — use **Highest**.

---

## 6. Close or resolve an issue

When an issue is complete, it must be **transitioned to Done** AND given a **resolution**.
Jira treats these as two separate fields — the transition changes the status (moves it off
the board); the resolution records *why* it was closed.

### Choosing a resolution

Use the table in Architecture Reference §7 for the full decision guide. Quick reference:

| Situation | Resolution |
|---|---|
| Bug fixed in code | **Fixed** |
| Story/Task/Improvement delivered | **Done** |
| Work will never be done (categorical) | **Won't Do** |
| Work postponed to a future version | **Deferred** — set `fixVersion` if known |
| Same as an existing open issue | **Duplicate** — add a `duplicates` link first |
| Bug investigated but not reproducible | **Cannot Reproduce** |
| Goal met another way (CBB) | **Handled Differently** |
| Evaluated and declined (CBB) | **Rejected** |
| Was in progress, then stopped (CBB) | **Cancelled** |
| Made irrelevant by later change (CBB) | **Obsolete** |
| None of the above | **Other** — **a comment explaining why is required** |

### Steps (web UI)

1. Open the issue in Jira.
2. Click the **status** button (e.g. **In Progress**) → select **Done** (or the
   applicable terminal transition for your workflow).
3. A **Resolve Issue** dialog appears. Select the appropriate **Resolution** from the
   dropdown.
4. If the resolution is **Duplicate**, confirm you have already linked the issue
   (`Link issue → duplicates`) before setting this resolution.
5. If the resolution is **Other**, add a comment on the issue before (or immediately
   after) closing it, explaining the close reason.
6. Click **Submit**.

> **Resolution field not appearing?** On some Jira configurations the resolution is not
> shown in the transition dialog. Go to **Jira settings → Issues → Workflows**, find the
> workflow, edit the **Done** transition, and add the **Resolution** field to its screen.

---

## 7. Start work: create a branch linked to an issue

This applies **post-1.0.0** (pre-1.0.0, all work is committed directly to the active
`dev-<version>` branch — no per-issue branches).

1. Open the Jira issue (e.g. `DOPE-42`).
2. Move it to **In Progress**.
3. In the **Development** panel (right side, populated by the GitHub for Jira app), click
   **Create branch**.
4. In the dialog, choose the **repository** and the **base branch** (the active
   `dev-<version>` branch).
5. Create, then **rename the branch** to match the convention:
   `dev-<version>-<JIRA-KEY>_<slug>` — e.g. `dev-1.0.1-DOPE-42_ble_timeout`.
6. From then on, any commit/PR mentioning `DOPE-42` auto-links to the issue.

---

## 8. Run a release in Jira

Jira's release tracking complements — it does not replace — the SDLC Release Checklist in
`CLAUDE.md`/`ScopeDOPE_SDLC.md`. Follow the SDLC checklist for the actual release gates; use Jira to
record the version.

1. Open the project → **Releases** (left sidebar) → select the version (e.g. `1.0.0`).
2. Confirm every issue with that **Fix version** is **Done**. Move or re-target any that
   are not.
3. When the SDLC Release Checklist is complete and the tag is cut, return here and mark
   the version **Released** (sets the release date).
4. Create the next version (e.g. `1.0.1`) so new issues can target it.

---

## 9. Edit a Confluence page

1. App switcher → **Confluence**.
2. Choose the space: **SCOPE** (ScopeDOPE Engineering, product/KB) or **CBBOPS** (internal
   operations).
3. Open a page → **Edit** (pencil icon) → make changes → **Publish**.
4. To add a page: **Create** (top bar), pick the space and a parent page, write, publish.

> Never paste engine internals, the DOPE-Blend methodology, or SPEC content into
> Confluence — those are trade secrets kept in OneDrive `04_-_Highly_Confidential/`.

---

## 10. Set the External Visibility default (one-time)

The External Visibility custom field needs its default set to `Hidden` by hand — there is
no API for it.

1. **Jira settings** (gear icon, top-right) → **Issues** → **Custom fields**.
2. Find **External Visibility** → **⋯ → Contexts and default value** → **Edit default**.
3. Set **Hidden** → save.

---

## 11. Clean up default resolutions (one-time)

This is a one-time manual step that must be performed after running `setup_atlassian.py`.
The REST API cannot delete or rename Jira's built-in default resolutions on the Free plan.

**Goal:** align the two Jira defaults that don't match CBB conventions.

1. Go to `https://coldboreballisticsllc.atlassian.net`.
2. Click the **gear icon** (top-right, Jira settings) → **Issues** → **Resolutions**.
3. Rename **Won't Fix**:
   - Click the pencil/edit icon next to `Won't Fix`.
   - Change the name to `Won't Do`.
   - Save.
4. Delete **Incomplete**:
   - Click the **Delete** icon next to `Incomplete`.
   - If Jira asks for a replacement resolution for existing issues that used it, choose **Done**.
   - Confirm.

After these steps, the resolution list should contain exactly the 11 CBB-standard
resolutions listed in Architecture Reference §7. Verify by checking the list.

> **Do not delete Done, Duplicate, or Cannot Reproduce** — they are correct as-is and
> used by the CBB resolution set.

---

## 12. API access for scripts

Some tasks (bulk operations, the rebuild script) use the REST API. Authentication is a
**Basic auth** pair: the admin email plus an API token.

The admin email and API token are stored in Key Vault. Pull them from there rather than
typing values by hand:

```bash
export JIRA_EMAIL=$(az keyvault secret show --vault-name kv-cbb-shared-prod --name atlassian-admin-email --query value -o tsv)
export JIRA_API_TOKEN=$(az keyvault secret show --vault-name kv-cbb-shared-prod --name atlassian-admin-api-key --query value -o tsv)
```

The token grants the admin's full access. **Never commit it** to any repository.

To rotate the token:
1. Create a new token at `https://id.atlassian.com/manage/api-tokens` (signed in as
   `admin@coldboreballisticsllc.com`).
2. Store it: `az keyvault secret set --vault-name kv-cbb-shared-prod --name atlassian-admin-api-key --value "<new token>"`
3. Revoke the old token from the same `id.atlassian.com` page.

> For interactive Jira/Confluence work, the preferred tool is the Atlassian MCP
> integration, not the REST scripts. The scripts in `cbb-utils/atlassian/` exist for
> batch and rebuild scenarios.

---

## 13. Configure ESUP → DOPE automation rules

**Purpose:** When a tester submits a bug or feature request via the ESUP portal, two
automation rules automatically create the corresponding issue in DOPE and immediately
close the ESUP ticket with a pointer to it. The tester sees a portal confirmation; all
actual work tracking lives in DOPE.

**Design:**
- ESUP `Bug —` request types → DOPE `Bug`, lands in backlog (no sprint)
- ESUP `Feature Request —` request types → DOPE `Improvement`, lands in backlog
- ESUP ticket is transitioned to Done and commented with the DOPE key
- 2 rules total; each covers all request types in its category via a single condition

Automation rules are configured through the Jira UI — there is no API for rule creation
on the Free plan. Allow approximately 10 minutes to build both rules.

**Before you start:** Sign in as `admin@coldboreballisticsllc.com` at
`https://coldboreballisticsllc.atlassian.net`.

---

### Rule 1 — Bug reports → DOPE Bug

#### Open the automation editor

1. In the left sidebar, click **ESUP** to open the project.
2. In the left sidebar, click **Project settings** (gear icon near the bottom).
3. In the Project settings menu, click **Automation**.
4. Click **Create rule** (top-right button).

#### Set the trigger

1. The rule editor opens with "Select a trigger."
2. Click **Issue created**.
3. Leave all options at their defaults.
4. Click **Save**.

#### Add a condition — filter by request type

1. Click **+ Add component** below the trigger.
2. Click **Condition**.
3. Search for and select **Issue fields condition**.
4. **Field:** `Request Type`
5. **Condition:** `is one of`
6. **Value:** select all seven Bug request types:
   - `Bug — Calculation / Accuracy`
   - `Bug — Crash or Freeze`
   - `Bug — Data / Session File`
   - `Bug — Performance`
   - `Bug — Printer / Label`
   - `Bug — Sensor / BLE Connectivity`
   - `Bug — UI / Display`
7. Click **Save**.

#### Add action — create a DOPE issue

1. Click **+ Add component** → **Action** → **Create issue**.
2. Set fields:
   - **Project:** `ScopeDOPE (DOPE)`
   - **Issue type:** `Bug`
   - **Summary:** click the field → click **{{}}** → enter `{{issue.summary}}`
   - **Description:** click the field → click **{{}}** → enter:
     ```
     {{issue.description}}

     ---
     _Submitted via ESUP portal — {{issue.requestType}} — original ticket: {{issue.key}}_
     ```
   - Leave Sprint and all other fields blank — the issue lands in the backlog.
3. Click **Save**.

#### Add action — transition ESUP ticket to Done

1. Click **+ Add component** → **Action** → **Transition issue**.
2. **Transition:** `Done` (or `Resolved` — whichever appears for the ESUP workflow).
3. Click **Save**.

#### Add action — comment on the ESUP ticket

1. Click **+ Add component** → **Action** → **Add comment**.
2. Comment body:
   ```
   Tracked in DOPE as {{createdIssue.key}}. You can close this ticket — work is tracked internally.
   ```
3. **Visibility:** `Shared with customer` — so the reporter sees it in the portal.
4. Click **Save**.

#### Name and enable

1. Click the rule name at the top and rename it to: `ESUP Bug → DOPE Bug`
2. Click **Turn it on** → confirm.

---

### Rule 2 — Feature requests → DOPE Improvement

Repeat all steps above with these differences only:

**Condition values** (select these 4):
- `Feature Request — Ammo Database`
- `Feature Request — Hardware Support`
- `Feature Request — Improvement`
- `Feature Request — New Feature`

**Create issue — Issue type:** `Improvement` (not Bug). Summary and description smart
values are identical.

**Rule name:** `ESUP Feature Request → DOPE Improvement`

---

### Verify both rules

1. Open the customer portal: in the ESUP project, click **View Portal** (top-right).
2. Submit a test ticket using any Bug request type. Use a clearly fake summary:
   `TEST — do not action`.
3. Return to Jira → **ESUP → Queues** — the ticket should already be Done with a comment
   showing a DOPE key.
4. Go to **DOPE → Backlog** — the Bug issue should be there with summary and description
   copied.
5. Repeat with a Feature Request type to verify Rule 2.
6. Delete both test issues when done (the ESUP ticket and the DOPE issue).

---

### Troubleshooting

**Request Type field does not appear in the condition dropdown:**
The field index occasionally lags on Free plan.
1. Exit the rule editor without saving the condition.
2. Go to **ESUP → Project settings → Request types** and confirm all request types are
   published (not in draft).
3. Wait 5 minutes, re-enter the automation editor — the field should now appear.

**`{{createdIssue.key}}` shows as blank in the comment:**
The smart value `createdIssue` is only available if the Create Issue action precedes the
Add Comment action in the rule. Verify the action order: Create → Transition → Comment.

---

## Document Control

| Field | Value |
|---|---|
| **Document owner** | `jschwefel@coldboreballisticsllc.com` |
| **Classification** | Confidential (03_-_Confidential/) |
| **Location** | `OneDrive/CBB_Corporate/03_-_Confidential/Infrastructure/Atlassian/Atlassian_Operating_Runbook.md` |
| **Cross-references** | `Atlassian_Architecture_Reference.md`; `Atlassian_Rebuild_Guide.md` |
| **Created** | 2026-06-06 |
| **Last updated** | 2026-06-06 |
| **Next full review due** | 2027-06-06 |

---

## Revision Control Block

| Rev | Date | Changed By | Reviewed By | Approved By | Summary |
|-----|------|------------|-------------|-------------|---------|
| 0.9 | 2026-06-06 | jschwefel | — | — | Initial release |
| DRAFT | 2026-06-10 | jschwefel | — | — | §6 Close or resolve an issue added (resolution selection guide + steps); §11 Clean up default resolutions added (one-time manual step); §§7–13 renumbered |
