Skip to content

AcuOps Installation Guide

Prerequisites

  • GitHub account with Actions enabled
  • Acumatica instance (2022 R2 or later, cloud or on-premises)
  • API user in Acumatica with access to the Customization API
  • GitHub CLI (gh) — recommended for setting secrets

Optional

  • yq — YAML processor (scripts degrade gracefully without it)
  • Python 3.10+ — for validate-project.py and deploy.py
  • PyYAML — for Python config loading (pip install pyyaml)

Setup Steps

1. Create Your Repository

Click "Use this template" on the AcuOps GitHub repo, or:

gh repo create my-acumatica-cicd --template studio-b-ai/acuops-pipeline --private
cd my-acumatica-cicd

2. Run the Setup Wizard

chmod +x scripts/setup.sh
./scripts/setup.sh

This generates acuops.yaml and prints the GitHub Secret commands.

3. Set GitHub Secrets

# Production credentials
gh secret set ACUMATICA_PROD_URL --body "https://your-instance.acumatica.com"
gh secret set ACUMATICA_PROD_USERNAME --body "api-bot"
gh secret set ACUMATICA_PROD_PASSWORD --body "your-password"
gh secret set ACUMATICA_PROD_TENANT --body "YourTenant"

# Staging (optional — falls back to production)
gh secret set ACUMATICA_STG_URL --body "https://your-staging.acumatica.com"
gh secret set ACUMATICA_STG_USERNAME --body "api-bot"
gh secret set ACUMATICA_STG_PASSWORD --body "your-password"
gh secret set ACUMATICA_STG_TENANT --body "StagingTenant"

# Slack notifications (optional)
gh secret set SLACK_WEBHOOK_URL --body "https://hooks.slack.com/services/..."

4. Set GitHub Variables

gh variable set CUSTOMIZATION_PROJECT_NAME --body "MyCustomization"
gh variable set ALSO_PUBLISH_PROJECTS --body "VARPackage,ShopifyConnector"

5. Add Your Customization Project

Export from Acumatica: 1. Go to SM204505 (Customization Projects) 2. Select your project 3. Source Control → Save Project to Folder (or Export Project to File) 4. Copy the exported project.xml into Customization/_project/

Or start from an example: 

cp examples/hello-world/project.xml Customization/_project/project.xml

6. Push and Deploy

git add -A
git commit -m "Initial customization project"
git push origin main

The pipeline runs automatically.

Acumatica API User Setup

Create a dedicated API user for CI/CD:

  1. Go to SM201010 (Users)
  2. Create user api-cicd (or similar)
  3. Assign role: Customization Administrator (minimum)
  4. Set a strong password

The user needs access to: - /entity/auth/login and /entity/auth/logout - /CustomizationApi/Import - /CustomizationApi/publishBegin and /publishEnd - /CustomizationApi/getProject (for backup)

Verifying the Installation

After pushing, check the Actions tab in GitHub. You should see:

  1. Build — Validates project.xml and creates .zip package
  2. Backup — Downloads current published package (if enabled)
  3. Deploy — Uploads and publishes to Acumatica