generator-mtaproject

Features

The MTA Project generator provides a single entry point to generate a fully configured, deployable SAP CAP MTA project — including sample data model, SAP Fiori applications, SAP BTP security configuration, multi-target Cloud Foundry deployment, and GitHub Actions CI/CD pipelines.

The generator is built on top of Yeoman, @sap/cds-dk and @sap/generator-fiori, and orchestrates these tools into one guided, question-based workflow.

Overview

• Freely configurable project name
• Optional sample schema, data (CSV) and CAP service
• Optional services with sample roles (user, admin), with mock users in package.json
• Optional cds add components:
  • hana
  • xsuaa (with XSAPPNAME and tenant mode)
  • html5-repo
  • mta (with optional srv-api destination and xs-app.json destination check)
  • workzone-standard
  • approuter (with automatic xs-app.json generation)
• Generate any number of SAP Fiori apps using the official @sap/fiori generator
  • Optional CSRF protection activation across all generated apps
  • Optional sample UI5 view with a table bound to the sample OData service
  • Automatic detection and correction of OData version 4.01 in manifest.json
• Automatic deployment to multiple SAP BTP / Cloud Foundry targets (org/space)
  • SSO or username/password login, shared or per-target credentials
  • Automatic redeploy after redirect URIs are added to xs-security.json
• Automatic maintenance of redirect URIs in xs-security.json
• Automatic generation of a project README.md containing service URLs, application URLs, target-specific information, and next steps
• Configuration files can be saved and reused later (--configFile)
• Create multiple GitHub Actions workflow files for CI/CD deployment to SAP BTP/Cloud Foundry via GitHub-hosted runners
  • Fail-fast Cloud Foundry login before the build step, with annotated error reporting
  • timeout-minutes safety net and per-target concurrency group
  • Tool version output (cf --version, mbt --version) for easier troubleshooting
• secrets.sh / secrets.ps1 scripts to create GitHub secrets via the GitHub CLI
• Guided local Git repository initialization (git init, add, initial commit)
• Guided GitHub repository creation via the GitHub CLI (gh), including organization selection, visibility, secret creation, push, and watching the triggered workflow run

Prerequisites

The following tools must be installed and available on your PATH:

• Node.js
• Yeoman — npm install -g yo
• SAP CDS Development Kit — npm install -g @sap/cds-dk
• SAP Fiori generator — npm install -g @sap/generator-fiori
• Cloud Foundry CLI (cf), logged in to your target SAP BTP subaccount
• MTA Build Tool (mbt) — npm install -g mbt
• MultiApps CLI Plugin for cf deploy
• (optional, for the GitHub integration steps) GitHub CLI (gh), authenticated via gh auth login

npm install -g yo
npm install -g @sap/cds-dk
npm install -g @sap/generator-fiori

Windows only: make must be installed, otherwise the generator will fail during mbt build, before deployment can happen.

A dedicated video tutorial showing how to install the required SAP CLI tools is available here: youtu.be/4gPXgPQLRsg

Installation

Install the generator globally from npm:

npm install -g generator-mtaproject

After installation, verify that Yeoman recognizes the generator:

yo

Make sure mtaproject is listed among the available generators.

Launch the generator

Start a new project

yo mtaproject

Reuse a previously saved configuration

yo mtaproject --configFile <saved-config-file>

Example:

yo mtaproject --configFile myproject-config.json

Note: Input prompts may occasionally not accept keystrokes right away. If this happens, press Enter once — input then works normally. If the generator appears stuck for more than a minute, the terminal may have been paused by an accidental keypress; press Backspace a few times, or Enter once, to resolve this.

Generator Wizard Steps

1. Project settings

• Project name — Required. Must not already exist in the current folder.
• Sample schema, data and service — Optional. If enabled, further asks for:
  • Service name (e.g. Catalog) — letters, numbers, -/_ only, must not start with a digit
  • Entity name (e.g. Books)
  • DB namespace (e.g. my.bookshop)
  • A matching CSV file with sample data is generated under db/data/

2. Roles & mock users

• Add services with sample roles (user, admin) — Optional. Generates a role-aware service definition (cat-service_roles.cds) instead of the plain version, and automatically enables XSUAA (see below).
• Add mock users for your roles in package.json — Optional. If enabled:
  • Password for the mock user and admin accounts
  • Option to assign both user and admin roles to the mock admin account
  • Automatically configures cds.requires.auth for [development] (mocked) and [production] (XSUAA)

3. SAP BTP building blocks

• HANA DB — Adds cds add hana --for production
• XSUAA Security — Adds cds add xsuaa --for production; automatically forced on if roles were added in step 2
  • XSAPPNAME
  • Tenant mode: Shared or Dedicated
• HTML5 Repository — Adds cds add html5-repo
• MTA descriptor — Adds cds add mta
  • Destination for the OData service — Adds a srv-api destination entry to mta.yaml
  • Check/correct xs-app.json destinations — Ensures all generated Fiori apps route OData calls through srv-api
• SAP Work Zone standard modules — Adds cds add workzone-standard
• App Router — Adds cds add approuter; generates app/router/xs-app.json automatically if both HTML5 Repository and XSUAA are enabled

4. SAP Fiori applications

The generator repeatedly launches the official @sap/fiori generator, so you can add as many applications as you need — SAP Fiori Elements or SAPUI5 freestyle, all OData V4.

After the Fiori apps have been generated:

• CSRF protection — Optional, activates csrfProtection: true on all XSUAA-authenticated routes in every generated app's xs-app.json
• Sample view with a table — Optional, for freestyle UI5 apps, inserts a ready-to-use list view bound to the sample OData entity
• OData 4.01 check & auto-correction — Detects and optionally corrects manifest.json files that declare OData version 4.01 (known to cause issues with SAP Build Work Zone) back to 4.0

5. Cloud Foundry deployment targets

• Auto deployment to Cloud Foundry — Optional. If enabled:
  • Same credentials for every target? — Use one cf login for all targets, or per-target credentials
  • Login method — SSO (browser-based) or username/password, with optional custom API endpoint
  • Target selection — Interactively choose one or more Org/Space combinations from cf orgs / cf spaces; already-configured spaces are filtered out automatically
  • Redeploy after redirect URI update — After the first deployment, the generator writes the resulting app routes into xs-security.json as redirect URIs. Optionally triggers a second, automatic deployment so the XSUAA service picks up the updated redirect URIs. Defaults to off if GitHub Actions is also enabled, since the CI/CD pipeline will handle this instead.

6. GitHub Actions CI/CD

• Add GitHub Actions workflow for deployment — Optional. For each configured deployment target, you can define:
  • Workflow name and filename
  • Target branch (default main)
  • Cloud Foundry API endpoint and Node.js version (shared across all workflows)
  • GitHub secret names for the Cloud Foundry username and password

Each workflow file is generated under .github/workflows/ and:

• Runs on ubuntu-latest, with a timeout-minutes safety net and a concurrency group per org/space (queues overlapping deployments instead of cancelling or running them in parallel)
• Is clearly structured into three phases: container setup (checkout, Node.js, Java, Cloud Foundry CLI, MultiApps plugin), deployment prep (Cloud Foundry login, npm ci, mbt install), and deployment (mbt build + cf deploy)
• Performs the Cloud Foundry login first, before the (potentially long) build step — so a bad credential fails fast instead of wasting build time
• Reports a clear, annotated error if the login step specifically fails, pointing at the two secret names to check
• Prints a short success confirmation after deployment completes

Example generated workflow (simplified):

# Auto-generated by generator-mtaproject — safe to edit, not overwritten on regeneration
name: Deploy to my-org - PROD
on:
  push:
    branches: [ "main" ]
  workflow_dispatch:
concurrency:
  group: deploy-my-org-PROD
  cancel-in-progress: false
jobs:
  build-and-deploy:
    runs-on: ubuntu-latest
    timeout-minutes: 45
    steps:
      - uses: actions/checkout@v5
      # ... Node.js, Java, Cloud Foundry CLI, MultiApps plugin ...
      - name: Cloud Foundry login
        id: cf_login
        run: cf login -a https://api.cf.eu10.hana.ondemand.com -o my-org -s PROD ...
      - name: Report login failure
        if: steps.cf_login.outcome == 'failure'
        run: echo "::error::Cloud Foundry login failed. Check that the secrets CF_USERNAME and CF_PASSWORD are set correctly."
      # ... npm ci, mbt build --mtar archive.mtar ...
      - name: Deploy
        run: cf deploy mta_archives/*.mtar
      - name: Deployment successful
        run: echo "✅ Deployment to org my-org, space PROD completed successfully."

7. Git & GitHub repository setup

If the GitHub CLI is detected on your machine, the generator offers to finish the loop end-to-end:

• Create a local Git repository — git init, git add ., and an initial commit (custom commit message, default Initial Commit). The commit includes the full generated README.md.
• Create a GitHub repository — Choose an organization from gh org list (or -no organisation- for your personal account), pick a repository name, and choose public/private. Runs gh repo create <name> --source=. --private|--public.
• Create the GitHub secrets now — Runs gh secret set <name> for each Cloud Foundry username/password secret referenced by your workflows.
• Push and watch — Optionally git push right away, with a note that this may trigger an immediate CI/CD deployment, followed by an optional gh run watch to follow the triggered workflow run live.

Regardless of your answers above, secrets.sh (bash) and secrets.ps1 (PowerShell) are always generated, so the GitHub secrets can be (re-)created manually at any time using the GitHub CLI:

./secrets.sh

If the GitHub CLI is not available, the generator simply lists the required secret names for you to create manually in the repository settings.

Configuration Files

At the end of the prompting phase, you can save your answers to a JSON configuration file:

yo mtaproject --configFile customer-a-config.json

Benefits:

• Reuse a configuration to regenerate an equivalent project later
• Standardize project setups across a team
• Resume a generator run that was interrupted partway through — already-answered questions are skipped on the next run with the same config file

What gets generated

Project structure

• Full CAP project (db/, srv/, app/), MTA descriptor (mta.yaml), and (if selected) xs-security.json
• One or more SAP Fiori applications under app/
• .github/workflows/*.yml — one CI/CD workflow per deployment target
• secrets.sh / secrets.ps1 — helper scripts to (re-)create GitHub secrets
• README.md — project-specific documentation (see below)

Auto-generated project README.md

The generated project's own README.md (not this file — the one inside your new project) includes:

• Deployed routes per target
• Application IDs of all generated Fiori apps
• Full service and application URLs per target
• A Next Steps section covering role-collection assignment, Elements/UI5 app customization, Work Zone Launchpad configuration, redeployment, and a checklist of files worth customizing (xs-security.json, mta.yaml, manifest.json, package.json, per-app readme.md)
• The list of GitHub Actions workflows and the GitHub secrets they expect

Hints

At the end of a run, the generator prints hints relevant to your choices, e.g.:

• A reminder to protect app/router/xs-app.json manually if you added an App Router without HTML5 Repository or XSUAA
• A reminder that role collections need to be assigned to users, since roles were configured
• A reminder to check OData version 4.01 occurrences if you chose not to auto-correct them
• How to reuse your saved configuration file

Technologies

• Node.js
• Yeoman
• SAP CAP
• SAP HANA
• SAP BTP / Cloud Foundry
• SAP Fiori / SAPUI5
• MTA / MultiApps CLI Plugin
• XSUAA
• App Router
• GitHub Actions
• GitHub CLI (gh)

License

MIT

History

• 0.1.1 — Initial release with core features
• 0.1.2 — Automatic deployment and redirect URI maintenance
• 0.1.3 — CI/CD push to npmjs.com
• 0.1.4 — Bugfixes (logs, deployment), add README
• 0.1.5 — Use console.log() instead of this.log() for better output formatting
• 0.1.6 — Service name adjustment, roles (xs-security.json and service), mock users in package.json
• 0.1.7 — Bugfixes (redirect URIs without App Router), OData version 4.01 check in manifest.json
• 0.1.8 — Destination for OData service in mta.yaml, sample UI5 view, Next Steps in generated project README
• 0.1.9 — Renamed role collections in mta.yaml
• 0.1.10 — CI/CD fixes
• 0.1.11 — Already-selected spaces are filtered out when choosing further deployment targets
• 0.1.12 — Automatic redeployment after adding redirect URIs to xs-security.json
• 0.1.13 — Additional console output
• 0.1.14 — GitHub Actions workflow file generation
• 0.1.15 — secrets.sh / secrets.ps1 for creating secrets via the GitHub CLI
• 0.1.16 — Git init and GitHub repository & secrets creation
• 0.1.17 — Use v5 actions for Node.js & Java (Node.js 24 support)
• 0.1.18 — Initial commit now includes the complete README.md; notes on resuming an interrupted generator run
• 0.1.19 — Optimized GitHub Actions workflow: fail-fast Cloud Foundry login, timeout-minutes, concurrency group, tool version output, English step names, git push + gh run watch follow-up
• 0.2.1 - 2 different Project Modes (full and lean), Bugfixes (select deployment target), replace Space in org-Name in xsappname (mta.yaml), Fix (Workflow File)
• 0.2.2 - Adding Addition Options: MCP Server