aicoded.dev

Publishing: sending an app to the platform

aicoded publish sends a commit of an app to the platform's delivery pipeline, which checks it and writes a change record for it, and aicoded status shows the outcome. This guide covers signing in, the clean commit, what is sent, the waiting, reading the outcome, what the delivery pipeline checks, the preview every publish is held for until you ask for its release, publishing straight to production, and the codes.

Signing in

Publishing uses your sign-in to the platform: run aicoded login --org <organisation> once, as the tools explain. Without a sign-in, or with one that has ended, aicoded publish and aicoded status fail with E-CLI-004. Signing in needs a person and a browser, so an AI assistant asks you to run aicoded login.

The first publish of an app's name creates the app in your organisation, with you as its owner. Only its owner publishes it again: another builder's app is E-PUB-005, and an app that an administrator archived is E-PUB-006. A builder creates at most 10 apps a day (E-PUB-008).

The clean commit

A publish sends a commit, never the files as they are on disk. Before anything leaves your computer, aicoded publish refuses:

Run aicoded check --frozen first: it runs the tests too, and reports every generated file that is out of date (E-CHK-001). Run aicoded generate, or aicoded check without --frozen, and commit what it writes.

What the commit holds

What is sent

The bundle may be at most 32 MiB (E-PUB-009). A committed file stays in the history after you delete it, so keep large files out of the repository. aicoded runs git without your GIT_ environment variables, so that none of them points it at another repository, and passes every commit to git on its standard input.

The waiting

aicoded publish prints Published <app> at <commit> as <id>., then asks the platform for the outcome every 3 seconds, for up to 35 minutes, and prints each status as it changes: queued ..., then running .... Ctrl-C stops the waiting, not the publish, and prints the publish goes on: aicoded status <id>, as a wait that runs out of time does. --no-wait prints the id and returns at once.

aicoded status <id> prints what the end of the waiting prints, without waiting, and --json prints the publish as JSON. An id is pub_ and 26 lowercase letters and digits. Another shape is a command line that is not valid. An id that the platform does not know in your organisation is E-PUB-013, and a publish of another builder's app is E-PUB-005.

Reading the outcome

Published rooms at 1a2b3c4 as pub_hoskmcer6l2grf5cxrfq3ilioe.
queued ...
running ...
publish pub_hoskmcer6l2grf5cxrfq3ilioe of rooms at 1a2b3c4: Add the list of rooms
  checkout        passed
  modules         passed
  check           passed
  lint            passed
  secrets         passed
  vulnerabilities passed
  licences        passed
  sbom            passed
  capabilities    passed
  migrations      passed
  data            passed
  build           passed
  tests           passed
  attacks         failed
  personal-data   passed
  rooms: pages/rooms/n_id/index.html:1: E-GATE-032: POST /rooms/7 (form close) as another viewer with the roles staff: answered 303, expected 403 or 404
    fix: check ownership in the page's Guard, which runs before every form, not in Data or Process
    docs: https://aicoded.dev/docs/errors/E-GATE-032
  note: rooms: deps/rooms.go:31: E-GATE-025: //nolint:errcheck silences a check
    fix: remove the directive and fix what the check reports
    docs: https://aicoded.dev/docs/errors/E-GATE-025
  checks: the security checks of layers L1 to L5, L8 and L9, and the simulated attacks (L7), ran
  change record 7
failed: 1 problem

The last line is the status: queued, running, or how the publish ended. For a failed publish it counts the problems; notes do not count.

Status What it means Exit code
passed every step passed 0
failed a step found problems 1
refused the platform could not read the commit from what was sent (E-PUB-014) 1
error the delivery pipeline could not finish, through a fault of its own (E-PUB-011) 1

Each problem has its code, file:line, fix and docs link, as in aicoded check: fix it as you would a problem of aicoded check, commit, and publish again. Each note follows the problems, on a line that starts with note:, with the same parts. After refused or error, publish a new commit, even an empty one made with git commit --allow-empty.

Every publish gets a change record when it ends, whatever its outcome: who asked, with the summary, what changed, and which checks ran, each with its layers, its outcome and how many problems and notes it found. When the simulated attacks ran, it also counts the app's pages and those the attacks reached, and lists those they did not. Its number is on the line change record.

What the delivery pipeline checks

The delivery pipeline runs these steps in this order. Each scanner, the build, the tests and the app under attack run in a sandbox of their own, with no network. The layers are those of the security checks, which the change record names too.

Step Layers What it does Stops the publish on
checkout none verifies the bundle and takes the commit out of it a bundle it cannot read (refused), a symbolic link (E-GATE-009), a commit too large (E-GATE-010)
modules L1 Approved parts only checks go.mod, go.sum and the permission list, and fetches the modules the app may use E-GATE-001 to E-GATE-008, E-GATE-011, E-GATE-026 and E-GATE-027
check L1 Approved parts only, L5 Every page locked runs aicoded check --frozen --no-tests of the framework version the app requires its problems
lint L1 Approved parts only runs golangci-lint with staticcheck (its checks of bugs and style, not its simplifications or quick fixes), gosec, errcheck, bodyclose and sqlclosecheck, and reads every Go file for directives any finding (E-GATE-013 to E-GATE-017), a //go:debug comment (E-GATE-026)
secrets L4 Leaked passwords runs gitleaks over the commit and its history any secret (E-GATE-018 and E-GATE-019)
vulnerabilities L3 Known weaknesses runs OSV-Scanner, then govulncheck, over the modules the app uses a critical weakness the app calls (E-GATE-020)
licences L3 Known weaknesses reads the licence of each module with go-licenses nothing
sbom L3 Known weaknesses lists the app's modules with Syft, as an SBOM nothing
capabilities L2 Stays in its limits follows the app's calls to the network, files and other capabilities with capslock nothing
migrations L9 Safe data changes checks the draft of schema changes that the publish carried, .aicoded/migration.sql, with the rules of aicoded check, and refuses a commit that holds the draft; a destructive change is the note E-MIG-003 E-MIG-001, E-MIG-002 and E-MIG-006
data L8 Stays in its limits notes the data that may reach the app's mail, as aicoded check finds it, and each data class that the permission list adds nothing
build L1 Approved parts only builds the app's program a build that fails
tests L1 Approved parts only runs the tests with -race a failing test (E-CHK-004)
attacks L7 Simulated attacks starts the app it built and attacks it: requests without a session or a role, another viewer on each guarded page, and markup in every field E-GATE-029 to E-GATE-034 and E-GATE-036
personal-data L7 Simulated attacks searches what the app wrote during the attacks, its output and its spans, for what was entered in its forms E-GATE-035 and E-GATE-037
decision L10 Approval if needed decides on the release against the app type: Pre-approved or Needs approval, with each reason a note (E-GATE-039 to E-GATE-048); see app types an app type, a group or a role that the organisation does not have, or data its source registry does not allow (E-REL-019 to E-REL-021), and a permission list that the platform's rules refuse whatever the app's framework version, such as a data class outside the four (E-MAN-008) or E-MAN-024

checkout and modules come first, and a problem in either skips the rest. The steps from check to data run no code of the app, and they run whatever one of them finds, so one publish shows every problem they find, with two exceptions: when check finds Go that does not compile (E-CHK-002) or go mod tidy fails (E-CHK-006), the steps that read the app's packages, lint, vulnerabilities, licences and capabilities, are skipped, while secrets, sbom and migrations still run; and data, which takes its notes from check, is skipped when check stopped before it read the app's code. The draft's problems that check finds show in migrations, and secrets scans the draft too: a secret there is E-GATE-018 at .aicoded/migration.sql:<line>. build and tests run only when all of them passed. attacks and personal-data run only when tests passed, on one run of the app, and personal-data is skipped when attacks ended in error or the app did not start (E-GATE-036). decision comes last, only when every other step passed. Simulated attacks says what each attack does and how to let the attacks reach every page. A step that runs out of time, memory or disk is E-GATE-012, and tests that stop the checks, or the go command that runs them (E-CHK-008), are E-GATE-028. A finding of a check that has no code of its own is E-GATE-000.

Each check runs with the platform's own configuration, so nothing in the app's repository, such as a .golangci.yml, a .gitleaksignore, a .gitleaks.toml, a gitleaks:allow comment, an osv-scanner.toml or a .syft.yaml, changes what it finds. The checks read generated files too, so a Code generated ... DO NOT EDIT line hides no file. The vulnerability databases are the platform's own copies; when they are more than a day old, the vulnerabilities step ends in error, and you publish a new commit later, as after any error.

A step reports problems, which fail the publish, and notes, which do not stop a publish. The change record counts the notes, and security sees them, so fix them when you can:

A known weakness that the app calls stops the publish when its score is 9.0 or more: the highest CVSS score of the weakness and its aliases, such as its CVE id, in the OSV database (E-GATE-020). A weakness of the Go standard library never stops it, since the platform chooses the Go that apps build with: it is a note, and your administrator updates Go.

//nolint and #nosec are honoured for now: golangci-lint skips the finding that a //nolint comment silences, and gosec the one that #nosec or //gosec:disable silences. But each such directive is a note (E-GATE-025) at its file:line, which the change record counts, and security sees them. Fix what the check reports instead of silencing it.

A godebug setting in go.mod and a //go:debug comment in a Go file change how Go behaves at run time, and some turn off its security defaults, so the delivery pipeline refuses both (E-GATE-026). Leave Go's defaults as they are. The go line of go.mod selects Go's defaults too, so the delivery pipeline also refuses a go line older than the release of the Go it builds with, such as go 1.25.0 when it builds with Go 1.26 (E-GATE-026): go mod edit -go=1.26.0 raises it.

A publish whose attacks step ran says checks: the security checks of layers L1 to L5, L8 and L9, and the simulated attacks (L7), ran. A publish whose lint, migrations and data steps ran but not its attacks, such as one whose tests failed or one to a platform that does not run the attacks yet, says checks: the security checks of layers L1 to L5, L8 and L9 ran; simulated attacks (L7) come later. Any other publish says partial checks: not every security check ran; the steps above say which, such as one that has not ended, one that a step before lint stopped, or one whose check found Go that does not compile; an older platform that runs only aicoded check and the tests says it of every publish.

Going live

A publish that passes is decided on at once, against its app type, and held for your preview until you ask for its release, as preview before release tells. The end of aicoded publish and aicoded status says what happens next, before the status line:

  change record 8
  Pre-approved by app type internal-tool.
  Held for preview, not live: its owner asks for its release with aicoded release pub_7kq2m4x5c3v6b5n6d2f7hjrt2a.
passed

Tell people the address that Live at or url gives: never work it out from the app's name. Only a live release has one, and a platform older than this aicoded gives none.

aicoded status --json and the release_status tool give the same in release: its tier (R1 for Pre-approved, R2 for Needs approval), its app_type, its reasons, its state (held, due, waiting, released, failed, replaced, refused or superseded), the reason of a refusal or a failure, whether it is live, and, while it is, its url, the address people open, and the publish it replaced with that one's state then, replaced_state; a declined approval card is in declined, with the approver's email as by, the reason and the time at. App types tells how the platform decides.

When a release stops at a schema change

When the platform releases a publish to production, it first applies the app's schema changes that the production database has not run yet, as schema changes tells. When one of them fails, the release stops and the version that runs keeps serving (E-MIG-005). The message names the step, as <publish>#<index>, and MySQL's error number, with a fixed short text such as MySQL error 1062 (duplicate key), never MySQL's own message, which can quote the app's data.

Preview

A publish that passed can run on the platform as the app's preview, so that you and a few people you pick try it before it goes live. Only the app's owner starts one: aicoded publish starts it with the publish it holds, as preview before release tells, and aicoded preview with the id of any publish that passed:

aicoded preview pub_7kq2m4x5c3v6b5n6d2f7hjrt2a
Preview of demo at https://demo.acme.preview.aicoded.cloud/ until 2026-11-13T10:00:00Z.
Invite up to five people in the console.

With aicoded mcp, the tools preview_publish and preview_end do the same. Your AI assistant calls preview_publish for a held publish when release_status's next says so, otherwise only when you ask, and preview_end only when you ask.

Preview before release

Every publish that passes is held for its owner's preview: it does not go live, and has no approval card, until you ask for its release. aicoded publish waits for the outcome, then starts the app's preview with the publish:

  change record 9
  Pre-approved by app type internal-tool.
  Held for preview, not live: its owner asks for its release with aicoded release pub_7kq2m4x5c3v6b5n6d2f7hjrt2a.
passed
Preview of demo at https://demo.acme.preview.aicoded.cloud/ until 2026-11-13T10:00:00Z.
Invite up to five people in the console.
The preview keeps its first end, reaches no outside service that production does not reach yet, and keeps its mail in the console.
It is not live. When the app's owner asks for its release: aicoded release pub_7kq2m4x5c3v6b5n6d2f7hjrt2a.

With aicoded mcp, release_status of a held publish says in next to start its preview with preview_publish and give you its address, and the release tool asks for the release. Your AI assistant calls release only when you ask.

Straight to production

aicoded publish --release skips the preview: once the publish passed, it goes live by itself when it is Pre-approved, and its approval card is made at once when it Needs approval, as if you had asked for its release the moment it passed. It prints It skips the preview: once it passed, it goes live by itself or waits for an approver. after the id, starts no preview, and its change record says the release was asked with the publish. When you no longer own the app by the time it passed, or it was archived, it is held instead. aicoded publish --release --no-wait returns at once, as --no-wait does. With aicoded mcp, the publish tool takes release: true, which your AI assistant sets only when you ask to publish straight to production. --preview, from older versions, is refused: holding is the default.

What security sees

Security will approve what the app may do, not its code. The permission list is that statement, so read it before you publish:

A page with no access rule does not generate at all. The permission list says which sections are enforced today, and which the platform only records for now.

The codes

aicoded explain <code> prints the page of each, as does the howto tool of aicoded mcp.

What the framework does not check yet

Some rules are yours to keep, since nothing checks them yet:

Running without the platform

An app runs only under a runner: on your computer that is aicoded dev. A minimal runner for running an app in production without the platform, aicoded run, comes later.

See also

Markdown · Source on GitHub · framework f46741f