Creating a workspace

Who this is for: the person bringing Broccoli into a company — the workspace owner, and the Org Admins who run day-to-day account administration afterwards.

Understand the shape before you build it

Broccoli has four levels. Getting these right on day one saves re-work later.

Workspace          your company — the tenant boundary
  └─ Organization  a business unit (e.g. Product, Platform, Research)
      └─ Manager   runs one team; owns that team's data
          └─ Team member

A workspace is a hard wall — nothing crosses between workspaces, ever. Organizations are a softer grouping inside it: they scope account administration and let leadership roll up across teams.

Rule of thumb: one workspace per company. One organization per business unit that has its own leadership and its own JIRA project. If two groups share a director and a backlog, they're one organization.

Before you start

Have ready:

• A workspace name and URL for your company (this becomes brocco.cloud/your-slug).
• The organizations you want inside it. You can add more later.
• Names and work emails for your leaders (Director / VP) and your team managers.
• Optionally, credentials for JIRA and GitHub — you can skip these and add them later.

You don't need to pre-create individual team members. Managers add their own rosters.

The setup wizard

Go to Get Started and work through the wizard. Only the workspace step is mandatory — everything else can be filled in later:

Step	What you enter
1. Workspace	Company name, URL, your name, email, password
2. Organizations	Your business units (optional — you get one default org)
3. Leadership	Directors and VPs, each assigned to an org (optional)
4. Teams	Team name, manager name and email, expected headcount (optional)
5. Connectors	JIRA / GitHub credentials — tested live before they're accepted
6. Done	Review — shows every seeded account and its temporary password

The wizard creates everything in a single transaction — it either all works or nothing is written. You land on the Org Admin page as the workspace owner.

Two things worth knowing:

• Connector credentials are validated before anything is saved. A bad JIRA token fails the signup rather than leaving you with a half-built workspace.
• The final review step is the only time temporary passwords are ever shown — copy them before navigating away. Everyone the wizard creates must change their password on first login; the workspace owner does not.

Connect JIRA and GitHub

Broccoli supports JIRA (issue tracking) and GitHub (code) as connectors, scoped two ways:

• Per organization — the JIRA project key(s) and GitHub org(s) that organization owns. This drives org-wide metrics dashboards.
• Per team — each manager narrows further on their own Profile page, by JIRA component, scrum/delivery team, or a raw JQL filter.

Once connected, roadmap items linked to a real ticket show live status, story points and assignee. GitHub panels show commits, PRs and review activity, refreshed every 15 minutes. JIRA results are cached for 30 minutes; if JIRA is unreachable, Broccoli deliberately shows the last good data rather than an empty board.

Credentials are encrypted at rest. Whoever operates your server must set an encryption key once and never change it afterwards — rotating it makes every stored credential permanently unreadable. Broccoli refuses to store credentials at all if the key is missing.

Bring people in

Three ways, in increasing order of self-service:

1. Create accounts directly from the Org Admin page — Managers, Directors, Executives.
2. Managers provision their own team members as Team Access (viewer) accounts from their roster.
3. Share a join link — one for requesting an org-level account, one for requesting Team Access to a specific team. Requests queue for approval: org requests go to the Org Admins, team requests go to that team's manager only.

Nobody self-approves. Every request, approval, denial and revocation is written to an append-only audit log, visible from Org Admin → Monitoring.