Gas City Doctrine Enforcement - Sessions perform work. Sessions are disposable. - Beads remember work. Beads/Dolt are the durable work substrate. - Convoys group work. - Mail coordinates work. - Formulas remember how. - Agents execute. - Packs configure. - Rigs scope. - Orders trigger. - Events prove what happened. - Work is not complete until verified and promoted.

(Do not create parallel work ledgers, agent-memory authorities, webhook daemons, or integration databases where native Gas City, Beads, GitLab, or existing Bluefly infrastructure already provides the capability).

Gas City & GitLab Integration Standard¶

Status: PROVISIONAL
Governance Notice: This standard remains PROVISIONAL / PROPOSED. Capability existence is not equivalent to a proven production integration. Promotion requires successful end-to-end validation against the canonical Oracle hq work authority.

1. Purpose¶

This standard defines the approved integration model between: - Gas City - Beads / Dolt - GitLab - GitLab CI - Bluefly's canonical Oracle factory infrastructure

The objective is to use upstream capabilities first, maintain one durable work authority, avoid redundant webhook and synchronization machinery, and preserve auditable execution.

The canonical integration direction is:

GitLab
  │
  │ native APIs / CI / issue integration
  ▼
Beads
  │
  ▼
Canonical Oracle Dolt hq
  │
  ▼
Gas City
  ├── Convoys
  ├── Orders
  ├── Events
  ├── Agents
  └── Rigs

There MUST NOT be an independent Mac synchronization authority.

2. Upstream-First Integration Order¶

In accordance with STD-015, use capabilities in this order:

Native Beads
bd gitlab
Beads/Dolt work state
Native Gas City
Events
Convoys
Orders
Agents
Packs
Native GitLab
Issues
Merge requests
Pipeline status
Native issue closing
Approval rules
Project/group settings
GitLab CI Components
blueflyio/gitlab_components
Existing Bluefly Infrastructure
Oracle Gas City supervisor
Canonical Dolt server
Tailscale
Cedar policy
Custom code
Only after an upstream gap is proven

Custom webhook daemons, standalone synchronization services, and Bash integration layers MUST NOT be introduced merely because an upstream capability has not yet been validated.

3. Canonical Authority¶

The canonical work authority is:

Oracle 127.0.0.1:3308 database: hq

Authenticated GitLab synchronization MUST operate against the canonical Oracle hq authority.

The following is prohibited:

GitLab ↓ Mac-local Beads/Dolt ↓ independent synchronization state

The required topology is:

GitLab ↕ bd gitlab ↕ Oracle hq ↕ Gas City

A local Mac City or local Beads store MUST NOT become a second GitLab synchronization authority.

4. Capability Proof Matrix¶

Capability / Construct	Evidence State	Classification
`bd gitlab sync / pull / push` commands exist	Verified in `bd 1.3.0`	`PROVEN_CAPABILITY`
`bd gitlab` narrow validation flags (`--dry-run`, `--pull-only`, `--issues`, `--project`)	Verified in `bd 1.3.0` help output	`PROVEN_CAPABILITY`
GitLab URL configuration	Accepted by `bd 1.3.0`	`PROVEN_CAPABILITY`
GitLab group ID `87749026` configuration	Accepted by `bd 1.3.0`	`PROVEN_CAPABILITY`
Session-scoped `GITLAB_TOKEN` authentication through 1Password	Verified	`PROVEN_CAPABILITY`
GitLab ↔ Beads authenticated round trip against Oracle `hq`	Not yet verified	`E2E_PENDING`
Private Tailscale Gas City transport	Mac → Tailscale → Oracle supervisor proven with remote `gc events` request	`PROVEN_DEPLOYED`
Supervisor `allowed_hosts` for canonical Tailscale hostname	Deployed and verified on Oracle	`PROVEN_DEPLOYED`
Remote `gc events` execution	Verified from Mac against Oracle context	`PROVEN_DEPLOYED`
Remote `gc status` / `gc mail` execution	CLI explicitly reports remote support not yet implemented	`KNOWN_CAPABILITY_GAP`
`gc convoy create/add/check/land`	Verified in deployed Gas City	`PROVEN_DEPLOYED`
`gc hook --claim`	Verified in deployed Gas City	`PROVEN_DEPLOYED`
`gc sling --owned / --no-convoy`	Verified in deployed Gas City	`PROVEN_DEPLOYED`
Shared Dolt server topology	Supported upstream and deployed by Bluefly	`PROVEN_DEPLOYED`
Supervisor webhook mount `/hook/{name}`	Present in Gas City implementation	`PROVEN_CAPABILITY`
`[[webhook]]` configuration	Present in Gas City implementation	`PROVEN_CAPABILITY`
`[webhook.verify]`	Present in Gas City implementation	`PROVEN_CAPABILITY`
`[[webhook.rule]]` order dispatch	Present in Gas City implementation	`PROVEN_CAPABILITY`
Webhook rate limiting	Present in Gas City implementation	`PROVEN_CAPABILITY`
Order `trigger = "webhook"`	Present in deployed Gas City	`PROVEN_CAPABILITY`
Public GitLab ingress to Gas City supervisor	Intentionally not established	`NOT_REQUIRED`
Custom MR auto-close Bash handlers	Duplicative of native capabilities	`REJECTED_UNLESS_GAP_PROVEN`

[!IMPORTANT] Do not promote a capability to PROVEN_DEPLOYED solely because: - the command exists; - source code contains the implementation; - configuration parses; - a binary includes the feature.

PROVEN_DEPLOYED requires runtime evidence.

5. Layer 1 — Native Beads / GitLab Synchronization¶

Classification: PROVEN_CAPABILITY / E2E_PENDING

Beads provides native GitLab synchronization capability.

Configuration:

bd config set gitlab.url "https://gitlab.com"
bd config set gitlab.group_id "87749026"

The GitLab token MUST NOT be persisted through:

bd config set gitlab.token ...

The secret authority is 1Password.

For an authorized interactive maintenance session, the token MAY be loaded once into the current shell environment and reused for related GitLab/Beads operations:

export GITLAB_TOKEN="$(op read 'op://BlueflyAgents/<item>/<field>')"

The token MUST NOT be:

written to Beads configuration;
committed to source control;
printed to logs;
stored in evidence receipts;
copied into shell scripts or documentation as a literal value.

The active shell environment is an approved temporary execution boundary. Re-reading or unsetting the token after every individual command is not required.

Narrow Validation Before Bulk Sync¶

A first validation MUST NOT begin with an unconstrained full-backlog bidirectional sync.

Use the narrowest available path first.

Examples:

bd gitlab pull <issue-ref> --dry-run

bd gitlab push <bead-id> --dry-run

or:

bd gitlab sync \
  --dry-run \
  --pull-only \
  --issues <issue-id>

When scoping with --project, the value MUST be an actual GitLab project ID, not the Bluefly group ID.

87749026 is the Bluefly GitLab group ID and MUST NOT be passed as a project ID.

Promotion Gate¶

This capability may be promoted to:

PROVEN_DEPLOYED

only after proving:

GitLab issue
    ↕
bd gitlab
    ↕
Oracle hq

with observed and attributable state changes.

The proof MUST identify:

GitLab project ID;
GitLab issue;
corresponding Bead;
Oracle Dolt database;
synchronization direction;
before state;
after state;
execution timestamp;
executing identity;
resulting evidence.

6. Native GitLab Issue Closure¶

Do not add custom MR-close handlers where GitLab's native issue-closing behavior is sufficient.

Preferred pattern:

Merge Request
  │
  │ Closes #123
  ▼
GitLab issue
  │
  ▼ bd gitlab synchronization
Beads work state

A custom script that directly runs:

bd close ...

from an MR webhook is redundant unless a concrete upstream limitation is demonstrated.

Any exception requires: - Documented gap - ADR - Tests - Named owner - Deletion condition

7. Layer 2 — CI Pipeline Reporting¶

Classification: PROVEN_UPSTREAM / BLUEFLY_COMPOSITION

Pipeline state should normally flow through:

GitLab Pipeline
  ├── GitLab API
  ├── GitLab CI components
  └── Native project/MR state

Bluefly standard CI components should report or expose relevant status using: blueflyio/gitlab_components

Agents may observe pipeline state through authorized GitLab access.

Do not create a public Gas City webhook solely to determine whether a pipeline passed or failed when the same information is already available through GitLab.

8. Layer 3 — Gas City Webhooks¶

Classification: PROVEN_CAPABILITY / ACTIVATION_DEFERRED

Gas City contains native webhook support.

Conceptual configuration:

[[webhook]]
name = "gitlab"
scope = "city"

[webhook.verify]
event_header     = "X-Gitlab-Event"
signature_header = "X-Gitlab-Token"
secret_env       = "GITLAB_WEBHOOK_SECRET"

[[webhook.rule]]
event  = "Pipeline Hook"
order  = "gitlab-pipeline-event"
target = "order"
args   = { status = "{{payload.object_attributes.status}}", ref = "{{payload.object_attributes.ref}}" }

This configuration MUST NOT be activated simply because the capability exists.

Activation requires a use case that cannot be handled adequately by: - Beads synchronization; - GitLab CI; - GitLab API observation; - Existing Gas City event handling.

9. Network Boundary¶

Gas City is private infrastructure.

The canonical Oracle endpoints are:

Gas City API:  https://bluefly-platform.tailcf98b3.ts.net     ↓ 127.0.0.1:8372
Dashboard:     https://bluefly-platform.tailcf98b3.ts.net:8443 ↓ 127.0.0.1:8082

Public ingress endpoints such as: - city.blutown.ai - api.blutown.ai - dash.blutown.ai

MUST NOT be required for ordinary Gas City operation.

Gas City must remain behind the authenticated Tailscale boundary unless a specific public-ingress requirement is approved.

A public GitLab webhook requirement therefore represents an architectural exception, not the default design.

10. GitLab-to-Gas-City Event Delivery¶

Because GitLab.com cannot directly call a private Tailscale endpoint, external webhook delivery MUST NOT automatically result in exposing the Oracle supervisor publicly.

Evaluate event delivery in this order: 1. GitLab native state 2. GitLab API 3. GitLab CI 4. Beads synchronization 5. Bluefly-controlled relay or event bridge 6. Direct public Gas City ingress — LAST

Any relay or event bridge must: - Have a defined owner; - Authenticate GitLab; - Authenticate downstream calls; - Expose the minimum required surface; - Preserve event provenance; - Implement replay protection where appropriate; - Avoid becoming a second workflow engine; - Avoid maintaining independent work state.

11. Remote Gas City CLI Constraint¶

The Mac operator context is:

[contexts.oracle]
city = "blucity"
url  = "https://bluefly-platform.tailcf98b3.ts.net"

The private remote transport is PROVEN_DEPLOYED.

Verified path:

Mac gc CLI
    ↓
Tailscale
    ↓
https://bluefly-platform.tailcf98b3.ts.net
    ↓
Oracle Gas City supervisor
    ↓
127.0.0.1:8372

Runtime proof:

gc --context oracle events --seq

successfully returned a live Oracle event sequence.

Therefore the remaining limitation is CLI command coverage, not networking, TLS, Tailscale routing, or Host validation.

Known command state:

gc --context oracle events
    → REMOTE SUPPORTED / PROVEN

gc --context oracle status
    → REMOTE NOT YET IMPLEMENTED

gc --context oracle mail ...
    → REMOTE NOT YET IMPLEMENTED

The tracked work item remains:

bc-1nt
Gas City CLI: implement remote context support for gc mail and gc status

Until those commands gain remote support, operational access may use:

SSH
 ↓
Oracle
 ↓
local gc command

This CLI limitation MUST NOT be worked around by restoring a Mac City as a second authority.

12. Supervisor Host Validation¶

Classification: PROVEN_DEPLOYED

The canonical Oracle Gas City supervisor explicitly permits the private Tailscale hostname:

allowed_hosts = [
  "bluefly-platform.tailcf98b3.ts.net",
  "127.0.0.1",
  "localhost"
]

This resolved the prior:

host_not_allowed

failure generated when Tailscale Serve forwarded the canonical private hostname in the HTTP Host header.

Remote execution through:

https://bluefly-platform.tailcf98b3.ts.net

has subsequently been verified.

Host validation MUST remain enabled.

Do not replace the allowlist with a wildcard or globally disable Host validation.

13. Secrets Policy¶

GitLab credentials MUST follow Bluefly's secrets constitution.

Secret authority¶

1Password

Approved execution boundary¶

Authenticated interactive shell environment
or approved 1Password runtime injection

Required behavior¶

1Password remains the canonical secret authority.
Secrets may be loaded into the current authorized shell environment for an active work session.
Environment variables may be reused across related commands in that session.
Configuration stores references or non-secret metadata, never plaintext secret values.
Logs and evidence MUST NOT expose secret values.
Repositories MUST NOT contain secret values.

Forbidden¶

bd config set gitlab.token <PAT>

Approved interactive pattern¶

export GITLAB_TOKEN="$(op read 'op://BlueflyAgents/<item>/<field>')"

bd gitlab <operation>
bd gitlab <operation>
bd gitlab <operation>

The token does not need to be repeatedly re-read or unset between commands in the same authorized shell session.

Agents MUST NOT:

enumerate unrelated 1Password items;
print tokens;
persist tokens into Beads configuration;
commit tokens;
copy tokens into documentation;
include token values in evidence receipts.

14. Work Authority Rule¶

A successful command on the Mac does not prove Oracle integration.

Commands MUST be classified by execution target: - Mac local discovery: gc ... $\rightarrow$ Mac City - Remote context: gc --context oracle ... $\rightarrow$ Oracle City, only where command supports remote execution - SSH Oracle: ssh bluefly-platform 'gc ...' $\rightarrow$ Oracle local execution

Integration evidence MUST identify which path was used.

15. Custom Integration Prohibition¶

Do not introduce: - gitlab-gascity-daemon - mr-close-handler.sh - gitlab-sync-service - webhook-state-db - integration-ledger - pipeline-watcher-daemon

unless the native stack has been proven insufficient.

Before approving custom integration code, document:

UPSTREAM_CAPABILITY=
WHY_INSUFFICIENT=
REQUIRED_BEHAVIOR=
OWNER=
TESTS=
SECURITY_BOUNDARY=
DELETION_TRIGGER=

Without those fields, custom integration work should be rejected.

16. Promotion Criteria¶

STD-032 remains provisional until the complete GitLab ↔ Beads path is proven.

Required evidence:

[x] GitLab authentication uses 1Password as secret authority.
[x] No GitLab token is persisted in Beads configuration.
[x] GitLab URL configuration is verified.
[x] GitLab group configuration is verified.
[x] Private Mac → Tailscale → Oracle Gas City transport is proven.
[x] Oracle supervisor Host validation accepts the canonical Tailscale hostname.
[x] Gas City remains private behind Tailscale.
[ ] Synchronization demonstrably targets canonical Oracle hq.
[ ] Known GitLab issue maps to known Bead.
[ ] GitLab → Beads change is proven.
[ ] Beads → GitLab change is proven where supported.
[ ] Resulting Dolt state is verified on Oracle.
[ ] No Mac-local synchronization authority is created.
[ ] No redundant custom synchronization daemon exists.
[ ] Integration evidence identifies actor, command, time, source, and resulting state.

Only after the remaining GitLab ↔ Beads round-trip conditions are satisfied may native bd gitlab synchronization be classified as:

PROVEN_DEPLOYED

17. Final Architecture¶

               GITLAB Issues / MRs / Pipelines
                              │
             ┌────────────────┼────────────────┐
             │                │                │
             ▼                ▼                ▼
         bd gitlab        GitLab API       GitLab CI
             │                │                │
             └────────────────┼────────────────┘
                              │
                              ▼
                   Canonical Oracle hq
                      Beads / Dolt
                              │
                              ▼
                           Gas City
             ┌────────────────┼────────────────┐
             │                │                │
           Agents           Orders           Events
             │                │                │
             └────────────────┼────────────────┘
                              │
                              ▼
               GitLab execution and release flow

Operator access:

Mac
 │
 │ Tailscale
 ▼
bluefly-platform.tailcf98b3.ts.net
 ├── :443  → 127.0.0.1:8372 (API)
 └── :8443 → 127.0.0.1:8082 (Dashboard)

There is one City authority.
There is one durable work authority.
GitLab integrates with that authority using upstream mechanisms first.
Custom integration exists only where evidence proves that upstream capabilities are insufficient.