Acumatica DevOps — Config-as-Code

What this repo is

This is a data repo of Acumatica configuration-as-code YAML. The sample config is Lab5 Gateway Works: a single-branch USD manufacturer that assembles IoT gateway kits (3 kits, 9 parts, 6 vendors, 7 customers).

The acu CLI lives elsewhere:

• Source and docs: https://github.com/kborovik/acumatica-cli
• Install from PyPI: https://pypi.org/project/acumatica-cli/

This repo holds YAML seeds (bootstrap/, baseline/, setup/, scenario/) plus the Bootstrap endpoint contract at bootstrap/project.xml (packaged by acu bootstrap / acu tenant create). Credentials stay local; never commit a plaintext .env.

The sample was verified against Acumatica ERP 26.101.0225, Default endpoint Default/25.200.001, Bootstrap endpoint version from bootstrap/project.xml (seeds use symbolic endpoint: bootstrap).

Quick start

1. Clone this repo

git clone https://github.com/kborovik/acumatica-gitops.git
cd acumatica-gitops

2. Install

uv tool install acumatica-cli

later: uv tool install acumatica-cli --upgrade

3. Configure your target

Create a .env in this repo (or any parent directory). acu finds .env by walking up from the current directory, so run all commands from inside this repo.

Required:

ACU_BASE_URL=https://your-instance.example/AcumaticaERP
ACU_TENANT=YOUR_TENANT
ACU_USER=admin
ACU_PASSWORD=...

Optional:

ACU_SSH=Administrator@your-host   # needed for tenant create / SSH control plane
ACU_API_VERSION=Default/25.200.001

Matching flags override env vars. Put flags before the subcommand: --url, --tenant, --username, --password, --ssh, --api-version.

Sanity-check the resolved target (no password in output):

acu config show
acu config check

4. Apply config

Preview first, then apply:

acu apply --dry-run 
acu apply 

Bare acu apply (no paths) defaults to bootstrap/, then baseline/, then setup/ in that order. Use that after a virgin tenant; use baseline/ setup/ when bootstrap is already in place.

5. Verify

acu diff 

Zero drift means success. There are no tests or linters in this repo. Validation is dry-run, then diff, then optional scenario run.

6. Optional: scenario and new tenant

acu run scenario/buy-build-sell.yaml

# virgin tenant: create + publish bootstrap package, then apply
acu tenant create --id N --login NAME
acu apply

acu tenant create needs ACU_SSH (or --ssh). It is resumable: an existing login skips create and republishes bootstrap.

Day-to-day commands

acu config show                         # resolved target (.env format, no password)
acu config check                        # read-only preflight: discovery, secrets, REST, SSH
acu apply --dry-run baseline/           # preview a path
acu apply baseline/30-ledger.yaml       # apply a single file
acu apply                               # defaults: bootstrap/ baseline/ setup/
acu diff baseline/58-order-types.yaml
acu run scenario/buy-build-sell.yaml
acu tenant create --id N --login NAME
acu schema --out schemas/               # dump swagger.json (schemas/ is gitignored)
acu --tenant <TENANT> <command>         # override sign-in tenant (no -t short flag)

Repo layout

• What — YAML under bootstrap/, baseline/, and setup/ (one file per config domain). Bare acu apply / acu diff use those three dirs in that order when given no paths. scenario/ is for acu run only; it is never applied or diffed.
• Where + who — your .env (ACU_* vars); keep credentials out of git.

Dir	Role
bootstrap/	Virgin-tenant seeds: features, company, credit terms
baseline/	Lab5 config upserts (GL, inventory, orders, AR/AP/CA, vendors, customers, kits)
setup/	One-shot actions with done_when (financial year, master calendar, open periods)
scenario/	Transaction scenarios for acu run; format contract: scenario/README.md

Apply order is the numbered filename prefix. Shell glob sorts alphabetically, so every cross-reference must sort after its dependency. Example: warehouse WH01 is in 53-warehouse.yaml, so it sorts before 54-item-classes.yaml. setup/ files use the same numbering and run after baseline/.

REST covers apply, diff, schema, and run. SSH is only for the tenant control plane (acu tenant create).

Reporting acu problems

If the tool fails (bug, crash, wrong diff, missing capability), file an issue on the CLI repo:

gh issue create --repo kborovik/acumatica-cli --title "..." --body "..."

Markdown standards

Write and edit every .md doc file (README, designs) with the steno skill. Simple technical language, lead-first sentences, no idiom. Apply the semantic line breaks convention (sembr.org) to sentences only. One sentence per line, break at sentence ends, never inside a sentence. A rendered paragraph needs a blank line, not a wrapped one.