Skip to content

Guides

Coordinate work on the company network

Bring builders together on a private company network, reserve items without duplicates and require a verify receipt in CI.

Create the private company network

The collective network gathers minimal projections from several maestros in a dedicated private repository. It does not receive the whole local state, credentials or panorama objects.

The company governs the policy and the enrollments. Each maestro publishes only to the path of its own enrollment.

First create the GitHub organization or the GitLab group and give the account used by Orkastery permission to create a repository under that owner. ork network empresa criar creates and rereads the private repository; the operation fails if the forge returns a different owner, a different path or public visibility.

The policy stores the coverage level, with --nivel observar, avisar or exigir, and the receipt version, with --recibo-versao. The local reservation guard stays mandatory at every level.

ork network empresa criar --forja github --dono <organization> --repositorio <network> --nivel avisar

Enroll each maestro with two authorities

First, the company runs ork network empresa inscrever and records the maestro’s expected identity: forge, host and numeric accountId. This operation neither accepts the enrollment nor creates local configuration.

Then the maestro signs in to the expected account and runs ork network empresa aceitar. Acceptance rereads the enrollment, resolves the authenticated account and refuses a different forge, host or accountId. Before accepting, check the destination, the policy version, the authorized projects and the published categories in the summary.

ork network empresa publicar resolves the account again, rebuilds and scans the projection before writing. ork network empresa status shows the published projection, its source and a pending publication.

ork network empresa sair ends the enrollment when the policy allows it. ork network empresa revogar stops new publications from an administered enrollment.

Writes use a single branch, without force, and each enrollment has its own path. Without access to the forge, nothing is queued: the local status stays pending and tells you to check login, access and reachability.

ork network empresa inscrever --empresa github:<org>/<network> --inscricao <id> --rede github:<org>/<network> --projetos github:<org>/<project> --account-id <n> --login <login>
ork network empresa aceitar --empresa github:<org>/<network> --inscricao <id> --rede github:<org>/<network> --projetos github:<org>/<project>
ork network empresa publicar --inscricao <id>
ork network empresa status --inscricao <id>

Reserve a roadmap item for the whole company

With an active enrollment, ork thread new --roadmap, ork roadmap pegar and ork_thread_new use the same operation: they reserve on the collective network first, then locally, and link the thread to the reservation. Without an active enrollment, the output stays as before, with no collective warning.

A collective reservation has a single holder. Another identity receives the holder’s enrollment, login, project and phase, and only joins as a collaborator (--coordenacao colaborador) or through an authenticated agreement (--coordenacao acordo), with a comment or note on the coordination issue checked through the forge API.

At the observar and avisar levels, coverage that is not configured, not checked or pending repair shows up in the output, and the operation continues. Under exigir, a new reservation or thread without a current check is refused; only an authenticated exception for the project and the item, with an owner, a justification and an expiry, lets the operation through.

Each attempt has an operationId. If a later effect fails, Orkastery undoes the local and collective effects in reverse order while the fingerprints still match; a mismatch leaves the operation pending. ork roadmap reconciliar repairs it, and repeating after the repair is safe.

ork roadmap pegar RM-NNN
ork thread new <name> --modo auto --roadmap RM-NNN --coordenacao colaborador
ork roadmap reconciliar RM-NNN --operacao op-<id>

What leaves the machine

The projection is a closed list: a field that is not on it does not leave. Out go the policy version and the enrollment; the maestro’s forge, host, accountId and current login; the controlled repository path; item id and state; reservations and work items with an opaque thread reference and phase; and relative patterns from touch_paths, lease and diff.

Local configuration, home, machine name, legal name, email, token, credential, local clone or raw remote, titles and free text, slug, branch, question, runtime, model, session and file content never leave.

Before sending, the projection goes through the dado_privado policy and the secret scan. An unavailable scanner or a finding blocks publication, without repeating the value found.

Publication writes the ork.rede-empresa-publicacao/v2 and ork.rede-empresa-publicacao/v3 contracts in the same transaction; v3 adds the paths per work item.

Conflict warning before the merge

The preflight compares work from different builders on the same project. There is a conflict when the item matches or when the path globs intersect. A pattern outside the accepted language (literal segments, *, ? and **) becomes a typed gap, not a conflict.

The suggested order follows each work item’s first appearance in the first-parent history. A shallow or truncated history comes out as inconclusive, and the local clock does not decide the order.

The same analysis shows up in ork network empresa status, ork ship publicar, ork ship pista, ork ci run, in ork_thread_status before ork_ship and before a direct ork ship. It is advisory at all three levels: it does not change a gate, authorization, verify, CI, lease, merge or push.

In PR or MR CI, the optional ORK_REDE_EMPRESA_READ_TOKEN secret, with read-only access to the network repository, lets ork ci run attach the preflight. Without it, or on a fork PR, the output says the collective check was not performed, and the CI result does not change.

ork network empresa status --inscricao <id> --json
ork ship pista <thread>

Require a verify receipt in CI

The receipt policy is opt-in per repository, through the ci.politica_recibo key in orkastery.yaml. Without the key, ork ci run --branch keeps the previous result and exit code; a value other than observar, avisar or exigir makes the manifest invalid.

observar reports the receipt state: presente, ausente, invalido or sha-divergente. avisar does the same and writes an annotation and job summary on GitHub, or a warning in the GitLab log. exigir fails a PR or MR targeting worktree.base_branch when the receipt is not present; a push to the protected branch itself does not get that failure.

ork ci prepare writes the ork.ci-projecao-replay/v1 projection into the bundle, without asserting a HEAD. In the PR or MR checkout, the runner validates the projection, reruns preparation, claims and commands through the same judgment as verify, in an allowlisted environment with no token, secret or credential, and emits ork.ci-recibo-runner/v1 with the executed HEAD.

The receipt is only present with at least one claim, commands and preparation identical to the verify in the target branch’s manifest and a complete green round. A current failure in preparation, a claim or a command fails at all three levels, with no exception for earlier debt: the projected baseline comes from the PR itself and does not enter the judgment.

The causes of an invalid receipt are closed, each with a message and an action: ci.recibo.projecao-acima-do-limite, ci.recibo.claim-nao-hermetica, ci.recibo.runner-sem-capacidade, ci.recibo.comando-nao-iniciado, ci.recibo.prazo-excedido and ci.recibo.produto-alterado.

# orkastery.yaml
ci:
  context: ork-verify
  politica_recibo: exigir

Make the check required and know its limit

The manifest defines the job’s behavior; the forge rule blocks the merge. On GitHub, protect orkastery.yaml and the workflow with CODEOWNERS and mark ork-verify as a required status check in a ruleset or branch protection rule. On GitLab, protect the base branch and turn on Pipelines must succeed.

The bundle and the sha256 come from the PR itself and can be forged by whoever controls the change. The anchor in the target branch’s manifest proves that the accepted recipe did not empty the claims or swap the protected commands or preparation.

It does not prove that the claims are complete or authentic, nor who wrote the bundle or the code. Protection against forgery is the signed receipt in RM-089’s F7, which has not shipped yet.

# CODEOWNERS
/orkastery.yaml @platform-team
/.github/workflows/ci.yml @platform-team