# Atlassian Rebuild Guide

# Cold Bore Ballistics, LLC

**Last updated:** 2026-06-10
**Purpose:** Reproduce the entire Atlassian instance from nothing — for disaster
recovery, or to hand a buyer's team a deterministic rebuild path.
**Audience:** A competent engineer with **no prior exposure to this instance.**
**Companion docs:** `Atlassian_Architecture_Reference.md` (what exists) ·
`Atlassian_Operating_Runbook.md` (day-to-day tasks).

> Most of the instance is codified as idempotent Python scripts in the `cbb-utils`
> repository under `cbb-utils/atlassian/`. The site itself, and a handful of Free-plan-
> blocked settings, must be done by hand — those are flagged **[MANUAL]** below. Running
> the scripts against an already-configured instance is safe: every step checks for
> existing resources and skips them.

---

## Table of Contents

1. [Prerequisites](#1-prerequisites)
2. [Step 1 — Create the site [MANUAL]](#2-step-1--create-the-site-manual)
3. [Step 2 — Add JSM and Confluence [MANUAL]](#3-step-2--add-jsm-and-confluence-manual)
4. [Step 3 — Run the setup script](#4-step-3--run-the-setup-script)
5. [Step 4 — Remove template sample content](#5-step-4--remove-template-sample-content)
6. [Step 5 — Manual settings the API cannot set](#6-step-5--manual-settings-the-api-cannot-set)
7. [Step 6 — Logos and avatars](#7-step-6--logos-and-avatars)
8. [Step 7 — GitHub for Jira [MANUAL]](#8-step-7--github-for-jira-manual)
9. [Step 8 — Issue migration (if applicable)](#9-step-8--issue-migration-if-applicable)
10. [What is codified vs. manual — summary](#10-what-is-codified-vs-manual--summary)

---

## 1. Prerequisites

On the machine running the rebuild:

- **Python 3.9+** and `pip install requests`.
- **GitHub CLI** (`gh`), authenticated with repo + issues scope — only needed for the
  issue-migration step.
- The `cbb-utils` repository checked out. The scripts live in `cbb-utils/atlassian/`.
- An **Atlassian API token** for the admin account. The token and email are stored in
  Key Vault — pull them 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)
  ```
  If rebuilding from scratch (Key Vault not yet seeded), create a new token at
  `id.atlassian.com/manage/api-tokens` and export it directly, then store it in KV
  once the vault is available.

> Multi-platform install notes for Python, pip, and the GitHub CLI are in the
> `cbb-utils` top-level README. Use the Microsoft/official installers for your OS
> (Debian, Ubuntu, RHEL/Fedora, Windows, macOS).

---

## 2. Step 1 — Create the site [MANUAL]

Atlassian has no single multi-product sign-up. You create the site by signing up for one
product, then add the others.

1. Go to `https://www.atlassian.com/` → **Sign in** → **Create an account**.
2. Use `admin@coldboreballisticsllc.com`. Verify the email.
3. Go to `atlassian.com/software/jira/pricing`, choose the **Free** plan, and **Sign up**.
4. When prompted for a site name, enter **`coldboreballisticsllc`**. The site becomes
   `coldboreballisticsllc.atlassian.net`.
   **This value is permanent and cannot be changed — confirm before proceeding.**
5. In the setup wizard, choose **Kanban** when asked for a methodology. Other wizard
   answers do not affect the final configuration.

---

## 3. Step 2 — Add JSM and Confluence [MANUAL]

1. Go to `https://admin.atlassian.com`, select the organization.
2. **Apps → Atlassian apps → Add app.** Add **Jira Service Management**. It provisions on
   the existing site (no new site is created).
3. Repeat for **Confluence** — it must share the same site for the JSM↔Confluence
   knowledge-base link to work.
4. Both are provisioned on a Standard/Premium trial. **Let the trial expire** with no
   payment method to land on the Free plan. No action needed.

---

## 4. Step 3 — Run the setup script

From the `cbb-utils` repository root:

```bash
python3 cbb-utils/atlassian/setup_atlassian.py
```

This idempotently creates everything codifiable:

- Groups (`jira-admins`, `jira-users`, `jira-reporters`, `jsm-agents`) and adds the admin
  to the first three appropriate ones.
- Site roles (`Developer`, `Reporter`) and the "CBB Software Projects" permission scheme.
- Projects **DOPE**, **CBB** (Jira Software / Kanban) and **ESUP** (JSM).
- The `Improvement` issue type on DOPE; components for DOPE and CBB; versions; epics.
- The **13 ESUP request types**, all using the `Service Request` work type.
- **Resolutions:** the CBB-standard set of 11 (Fixed, Done, Won't Do, Deferred, Duplicate,
  Cannot Reproduce, Handled Differently, Rejected, Cancelled, Obsolete, Other). The script
  creates any that are absent; Jira defaults matching by name are skipped. Two defaults
  require a rename/delete that can only be done in the UI — see Step 5.
- Custom fields **External Visibility** and **Repository** (the Repository field is
  created with 11 options and attached to the DOPE/CBB Default + Bug screens).
- Confluence spaces **SCOPE** and **CBBOPS** with their initial pages.

The script prints a list of remaining manual steps when it finishes. It is safe to re-run
at any time — existing resources are detected and skipped.

> **Free-plan note:** the script will report that it could not assign the permission
> scheme, project role actors, or Confluence space permissions. That is expected on Free
> (see Architecture Reference §11). On a Standard plan, re-running the script applies them.

---

## 5. Step 4 — Remove template sample content

Atlassian seeds sample issues and pages from the project templates. Remove them:

```bash
python3 cbb-utils/atlassian/cleanup_atlassian_samples.py
```

This deletes all sample issues, all ESUP request types (so the canonical 13 from setup are
the only ones), and sample Confluence pages — keeping only what the setup script created.

> Run order matters: run `setup_atlassian.py` first so the keepers exist, then cleanup.

---

## 6. Step 5 — Manual settings the API cannot set

These cannot be scripted on the Free plan. Each is detailed in the runbook; summarized
here as a checklist.

- **[MANUAL] Resolution cleanup** — after the setup script runs, rename and delete the
  two Jira default resolutions that don't match CBB conventions (Architecture Reference §7):
  **Jira settings → Issues → Resolutions:**
  1. Rename `Won't Fix` → `Won't Do`
  2. Delete `Incomplete`
- **[MANUAL] JSM portal groups** — create Report a Bug / Request a Feature / Other and
  assign the 13 request types (Runbook §4). The portal is empty until this is done.
- **[MANUAL] External Visibility default** — set to `Hidden` (Runbook §9).
- **[MANUAL] ESUP workflow / SLAs / automation** — optional operational maturity items
  (triage status, first-response and resolution SLAs, auto-assign rules). See the
  `cbb-utils/atlassian/README.md` manual-steps section for exact values.
- **[MANUAL] Board columns** — name the DOPE and CBB board columns per Architecture
  Reference §4–5.
- **[MANUAL] Confluence ↔ JSM knowledge base link** — in ESUP project settings, link the
  SCOPE space so KB articles are suggested to reporters.
- **[DEFERRED to Standard] permission scheme assignment, project role actors, Confluence
  space permissions** — applied automatically by re-running setup after upgrade.

---

## 7. Step 6 — Logos and avatars

Project avatars are set via REST API; site/user/Confluence-space logos are set in the UI.
Source images live in OneDrive `01_-_Public/Logos_and_Wordmarks/`.

**Project avatars (API)** — upload then assign (two calls each). Upload returns an `id`
used in the assignment call:

```bash
# Upload (returns {"id": ...})
curl -s -X POST \
  "https://coldboreballisticsllc.atlassian.net/rest/api/3/project/DOPE/avatar2" \
  -u "$JIRA_EMAIL:$JIRA_API_TOKEN" \
  -H "X-Atlassian-Token: no-check" -H "Content-Type: image/png" \
  --data-binary @"<absolute path to scopedope_icon_google_profile.png>"

# Assign (use the id returned above)
curl -s -X PUT \
  "https://coldboreballisticsllc.atlassian.net/rest/api/3/project/DOPE" \
  -u "$JIRA_EMAIL:$JIRA_API_TOKEN" -H "Content-Type: application/json" \
  -d '{"avatarId": <id>}'
```

Apply: **DOPE** and **ESUP** → ScopeDOPE icon; **CBB** → CBB logo.

**[MANUAL] Logos with no API** (do in the web UI):
- Confluence space logos: each space → **Space settings → Look and feel → Space logo**.
- Site avatar: **Jira settings → Look and feel**.
- Admin user avatar: `id.atlassian.com` → profile photo.

> Use **absolute** paths to the image files in `--data-binary` — relative paths fail
> depending on the shell's working directory.

---

## 8. Step 7 — GitHub for Jira [MANUAL]

1. In Jira: **Apps → Explore more apps** → search **GitHub for Jira** (by Atlassian) →
   **Get it now**.
2. **Apps → GitHub for Jira → Connect GitHub organization** → select **ColdBoreBallistics**.

After connecting, commits/branches/PRs containing a Jira key auto-link to issues.

---

## 9. Step 8 — Issue migration (if applicable)

Only relevant if rebuilding while open GitHub Issues still need importing. The current
instance is already populated, so this is a historical step.

```bash
# Phase 1 — create Jira issues, leave GitHub issues open, print a verification table
python3 cbb-utils/atlassian/migrate_github_issues.py

# Review the created Jira issues, then:
# Phase 2 — close the GitHub issues that are confirmed in Jira
python3 cbb-utils/atlassian/migrate_github_issues.py --close
```

The two-phase design ensures GitHub issues are never closed until their Jira counterparts
are verified. **`dope-format` is never part of any migration** — it stays on GitHub Issues
permanently.

---

## 10. What is codified vs. manual — summary

| Codified in `setup_atlassian.py` (idempotent) | Manual / UI-only |
|---|---|
| Groups, site roles, permission scheme | Site creation; adding JSM + Confluence |
| Projects DOPE / CBB / ESUP | Resolution cleanup (rename Won't Fix → Won't Do; delete Incomplete) |
| Components, versions, epics, Improvement type | JSM portal groups |
| Resolutions: target set of 11 (Fixed, Done, Won't Do, Deferred, Duplicate, Cannot Reproduce, Handled Differently, Rejected, Cancelled, Obsolete, Other); script creates any not already present | External Visibility default value |
| 13 ESUP request types (Service Request) | ESUP workflow, SLAs, automation rules |
| External Visibility + Repository custom fields (incl. screen association) | Board column naming |
| Confluence spaces SCOPE + CBBOPS and pages | Confluence space logos, site/user avatars |
| (On Standard) permission scheme + role + space-permission assignment | GitHub for Jira install/connect |

**The goal of this split:** everything reproducible is in version-controlled scripts (no
hand-built drift), and the irreducible manual steps are enumerated here so a new operator
can finish the rebuild without tribal knowledge. This is the acquisition-readiness
standard — reproducible infrastructure with a documented, complete manual remainder.

---

## Document Control

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

---

## Revision Control Block

| Rev | Date | Changed By | Reviewed By | Approved By | Summary |
|-----|------|------------|-------------|-------------|---------|
| 0.9 | 2026-06-04 | jschwefel | — | — | Initial release |
| DRAFT | 2026-06-10 | jschwefel | — | — | Step 3 updated to document resolution creation; Step 5 adds resolution-cleanup manual step; codified-vs-manual table updated |
