Skip to content

Collective Setup — Staging

This runbook walks through launching a new OpenCollective collective under the StartMeUp.NZ fiscal host, using OpsDev.nz as the worked example. It is the operator-facing procedure for ADR-0018 ("Launch OpsDev.nz as a fiscally-hosted collective"). The same steps apply to any future collective; replace the slugs and YAML entries to suit.

OpsDev.nz is collective zero — the first collective hosted by StartMeUp.NZ. Working through this procedure for OpsDev.nz is what produces the worked example for everyone who comes after.

What this runbook covers

  1. Creating the collective in staging and verifying it is hosted correctly.
  2. Promoting the same configuration to production once staging is signed off.

What this runbook does not cover

  • Host setup. This runbook assumes the StartMeUp.NZ fiscal host organisation (startmeup-nz) already exists on the target OpenCollective environment with isHost: true and an admin account available to approve host applications. Creating the host is a separate one-time task per environment; it is not covered here.
  • Token rotation and credential management. See oc-opsdevnz authentication design for token lifecycle and 1Password setup.
  • Stripe / financial contributor setup. That happens after the collective is hosted, in the OpenCollective web UI.

Prerequisites

  • Python 3.12+ with oc-opsdevnz (0.2.5+) and op-opsdevnz installed from PyPI. Either:
  • uv tool install oc-opsdevnz op-opsdevnz — system-wide CLI install, preferred for an operator running this runbook.
  • uv sync in the startmeup.nz or opsdev.nz repository — installs the pinned version (currently oc-opsdevnz>=0.2.5) into that repo's venv. Use whichever repo you are working from.

Avoid running uv sync inside public/opsdev.nz/modules/oc-opsdevnz/ for this runbook — that venv is for developing the module, not for using it. Pip-installing the module editable from a parent repo also creates the same confusion; the parent repos should consume the released version from PyPI. - 1Password CLI authenticated (op signin) or a service-account token in OP_SERVICE_ACCOUNT_TOKEN. - An OpenCollective staging account with admin rights on the fiscal host organisation (startmeup-nz on staging). - A Personal Token with account and host scopes. Resolve from 1Password via OC_SECRET_REF (preferred) or set OC_TOKEN directly for short runs.

Configuration files

The authoritative YAML for the StartMeUp.NZ fiscal host lives in the startmeup.nz repository under opencollective/:

File Purpose
opencollective/staging-host.yaml StartMeUp.NZ host profile (staging)
opencollective/staging-collectives.yaml Collectives hosted on staging
opencollective/staging-projects.yaml Projects under those collectives
opencollective/prod-host.yaml StartMeUp.NZ host profile (production)
opencollective/prod-projects.yaml Projects under StartMeUp.NZ (legacy)

OpsDev.nz-specific entries are already present in the staging files. When launching a new collective, add a new entry to the appropriate YAML file and follow the steps below.

1. Validate locally with the mock API

Before touching the shared staging environment, run the same commands against the local mock API. This catches YAML errors, payload mistakes, and missing-field problems in seconds rather than minutes.

Keep the mock in sync. Update public/opsdev.nz/opencollective/mock/ when the API, YAML shapes, or CLI change.

# From the opsdev.nz repository
cd opencollective/mock
./run-mock.sh

The script starts the mock server, runs hosts, collectives, and projects against it, and prints what would have changed. See the local mock development guide for details on what the mock does and does not cover.

2. Authenticate to 1Password and resolve the staging token

# Interactive — eval the output so the session vars land in this shell
eval $(op signin)

# Or, for automation, set the service-account token
export OP_SERVICE_ACCOUNT_TOKEN="..."

# Point the CLI at the staging OpenCollective token
export OC_SECRET_REF="op://startmeup.nz/opencollective-staging-automation/token"

# Override for a one-off run
# export OC_TOKEN="..."

The CLI defaults to production; you must pass --staging (or its alias --test) for every command in this runbook.

3. Verify current state

Confirm the token resolves and the staging account is reachable:

oc-opsdevnz whoami startmeup-nz --staging
# Expect: account with type ORGANIZATION

oc-opsdevnz whoami opsdevnz --staging
# Expect: GraphQL error containing "No account found with slug 'opsdevnz'"
#         the first time. After step 5, expect a COLLECTIVE entry.

4. Create the collective and apply to host

This is the new step. opsdevnz does not yet exist on staging as a collective; this command creates it and submits an apply-to-host request to startmeup-nz.

oc-opsdevnz collectives \
    --file opencollective/staging-collectives.yaml \
    --staging

The command will:

  1. Create the collective opsdevnz if it does not exist.
  2. Update name, description, and tags to match the YAML.
  3. Submit an applyToHost mutation to startmeup-nz with the message from the YAML's host_apply_message field.

A successful response looks like:

{
  "slug": "opsdevnz",
  "created": true,
  "updated": false,
  "applied_to_host": true,
  "account": {
    "id": "...",
    "slug": "opsdevnz",
    "name": "OpsDev.NZ",
    "type": "COLLECTIVE",
    "host": { "slug": "startmeup-nz", "name": "StartMeUp.NZ" }
  }
}

The apply-to-host request is a request, not an approval. The fiscal host admin still needs to approve it. Continue to step 5.

5. Approve the host application (UI)

The applyToHost mutation submits a pending request. To finalise the relationship, an admin of startmeup-nz must approve it in the web UI.

The account that can approve is an admin of the startmeup-nz host organisation on staging — this is typically a different account from the one whose token oc-opsdevnz is using. The automation token is a service account for the collective creator; the host admin user is a separate staging login (e.g., the SMUNZ-side admin user) with rights on the host. In a single-operator setup, the same person may control both accounts and just switch logins.

  1. Sign in to https://staging.opencollective.com as the host admin (admin of startmeup-nz), not as the collective creator.
  2. Navigate to the host's pending applications (Settings → Host → Applications, or the host admin dashboard).
  3. Approve the application from opsdevnz.
  4. Note the optional message back to the collective (e.g., "Welcome, collective zero.").

There is no public GraphQL mutation for host approval; the UI is the only path. This is the only manual step in the runbook.

On some staging environments, the apply-to-host request is auto-approved by the host admin. If the activity log shows application approved immediately after step 4 — with no manual UI action — skip this step and proceed to step 6. Production is unlikely to behave this way; this note is for the staging case only.

After approval, optionally re-run step 4 to confirm the relationship landed. Expect created: false, updated: false, applied_to_host: false (idempotent), and account.host.slug: "startmeup-nz". This re-run is for verification only; the approval itself is what completed the hosting. The next action is step 6.

6. Create the projects under the collective

Once the collective is approved, create the projects listed under it. For OpsDev.nz, that is the Platform Engineering project and the two event projects (DevOpsDays Wellington 2027, Software Freedom Day 2026).

oc-opsdevnz projects \
    --file opencollective/staging-projects.yaml \
    --staging

The CLI is idempotent: re-running it is safe and will only update projects whose metadata has changed. Each project requires a parent_slug matching the collective (opsdevnz for OpsDev.nz projects). Parent collectives must exist first.

If you only need to apply one project (e.g., during incremental work), filter with --only:

oc-opsdevnz projects \
    --file opencollective/staging-projects.yaml \
    --staging \
    --only platform-engineering

7. Verify in the staging web UI

Open https://staging.opencollective.com/opsdevnz and confirm:

  • The collective page shows the StartMeUp.NZ fiscal host badge.
  • Name, description, and tags match staging-collectives.yaml.
  • The Platform Engineering project appears under the collective with the correct description and tags.
  • The two event projects appear with their own budget chips (zero balance expected at this stage).
  • The Tags section lists every tag from the YAML.

If any field is wrong, edit the YAML and re-run the corresponding oc-opsdevnz command. Re-running produces an editAccount mutation updating only the changed fields.

8. Promote to production

Once staging is signed off, promote the same configuration to production. Production defaults are baked into the CLI: drop --staging and the OC_SECRET_REF (or OC_TOKEN) points at the production token.

The OpenCollective production API is https://api.opencollective.com/graphql/v2. The CLI targets it by default. Production slugs and copy live in the prod-*.yaml files in the startmeup.nz repo.

# 1. Verify the production token
oc-opsdevnz whoami startmeup-nz          # no --staging → prod
oc-opsdevnz whoami opsdevnz              # expect 404 (not yet created in prod)

# 2. Create the collective and apply to host
oc-opsdevnz collectives --file opencollective/prod-collectives.yaml

# 3. Approve the host application in the production UI
#    https://opencollective.com → startmeup-nz → pending applications

# 4. Apply the projects
oc-opsdevnz projects --file opencollective/prod-projects.yaml

# 5. Verify on https://opencollective.com/opsdevnz

Adapting this runbook for a new collective

To launch a new collective under StartMeUp.NZ:

  1. Pick a slug. It becomes the URL fragment on opencollective.com/<slug> and is permanent — choose carefully.
  2. Add an entry to opencollective/staging-collectives.yaml with host_slug: startmeup-nz, apply_to_host: true, and a host_apply_message that introduces the collective to the host admin.
  3. Add any projects to opencollective/staging-projects.yaml with parent_slug pointing at the new collective's slug.
  4. Run steps 1 through 7 of this runbook against staging.
  5. Once signed off, repeat against production.

Future collectives that apply directly through the OpenCollective web UI (rather than being created by StartMeUp.NZ) follow a different path: the host admin receives a pending application and either approves or rejects it. Once approved, add the collective to staging-collectives.yaml with apply_to_host: false to keep the inventory in sync.