Getting Started with AcuOps

This guide walks through setting up AcuOps for a new Acumatica environment.

Prerequisites

• Acumatica Cloud or on-premise instance (version 24.1+)
• GitHub organization or repository access
• API user account in Acumatica with admin role
• Railway account (for hosted monitoring)

Step 1: Create an API User

In Acumatica, navigate to SM201010 (Users) and create a dedicated API user:

• Login: api-bot (or your preferred name)
• Roles: Assign roles with read access to all entities you want to monitor
• Important: Use a strong password — this account authenticates all API operations

caution

Acumatica licenses limit concurrent API sessions (~2-3). AcuOps uses a Redis session gate to coordinate access across services.

Step 2: Set Up a Client Repository

AcuOps is split into two pieces:

• acuops-pipeline — the reusable CI/CD engine (shared across all clients)
• client-<name> — a thin, per-client repo holding only that instance's customization, config, and secrets

You don't fork or template the engine. You create a client repo that calls it.

The full steps live in the canonical CLIENT-ONBOARDING.md on acuops-pipeline. The short version:

1. Create studio-b-ai/client-<name> (private).
2. Copy examples/client-repo/ from acuops-pipeline into the new repo root.
3. Populate acumatica/Customization/<YourPackage>/ with your exported project (see Step 3).
4. Fill in acumatica/acuops.yaml — client-asthetik is the reference implementation.
5. Add acumatica/instance-manifest.json.
6. Configure Acumatica + ACUOPS_AGENT secrets (see table below).
7. Install the acuops-agent GitHub App on the new repo.
8. Set repo variable ACUOPS_PIPELINE_VERSION to v1 (floating, recommended) or a specific patch tag.
9. Open a test PR to validate the wiring.
10. Merge to main to deploy.

Configure GitHub Secrets

Secret	Value
ACUMATICA_PROD_URL	https://your-instance.acumatica.com
ACUMATICA_PROD_USERNAME	API user login
ACUMATICA_PROD_PASSWORD	API user password
ACUMATICA_PROD_TENANT	Tenant name
ACUOPS_AGENT_APP_ID	GitHub App ID (from Studio B)
ACUOPS_AGENT_PRIVATE_KEY	GitHub App private key (from Studio B)

Step 3: Export Your Customization Project

1. Open Acumatica → SM204505 (Customization Projects)
2. Select your project
3. Source Control → Save Project to Folder
4. Commit the exported files to acumatica/Customization/<YourPackage>/ in your client repo

Step 4: Deploy

Push to main to trigger the deploy pipeline. The thin caller workflow in your client repo invokes acuops-pipeline@v1, which will:

1. Validate the project XML
2. Package into a .zip
3. Import via the Customization API
4. Publish (co-publishing with any projects listed in acuops.yaml)
5. Report results

Step 5: Set Up Monitoring

Deploy the test suite for ongoing validation:

gh repo create your-org/acumatica-tests --template studio-b-ai/ui-test-suite --private

Configure the same Acumatica secrets plus:

Secret	Value
SLACK_WEBHOOK_URL	Incoming webhook for notifications

The test suite runs daily at 6am UTC and after every deploy.

Next Steps

• Deploy Pipeline — Understand the 5-step deploy process
• Customization Guide — Write DAC and graph extensions
• Troubleshooting — Common deploy failures and fixes