This repository contains Automation Portal plugins and shared SDK packages for Backstage and Red Hat Developer Hub (RHDH): Portal host contracts, self-service workflows, AAP integrations, and APME quality contributions.

• Overview
• Features
• Prerequisites
• Getting Started
  • Initial Setup
  • Configuration
  • Running Locally
• Repository Structure
• Available Plugins
• Development
  • Testing
  • Building
• Troubleshooting
• Documentation
• Changelog
• Contributing
• Security
• License

The Ansible Backstage Plugins project brings Ansible Automation Platform capabilities into Backstage, enabling developers to:

• Browse and launch job templates
• Manage inventories, projects, and credentials
• View job execution history and results
• Create self-service automation workflows
• Integrate AAP with software catalogs
• Generate scaffolder actions for AAP resources

Packages are organized into Portal core, self-service, AAP, and APME workspaces. The source app defaults to native NFS composition. APME demonstrates a third-party contributor without direct dependencies on self-service page components.

This branch is an experimental SDK implementation. Native composition does not complete content extraction or establish production compatibility for every RHDH version. See the implementation guide.

• Frontend Integration: Browse resources directly in Backstage UI
• Self-Service Automation: Enable developers to trigger automations without AAP knowledge
• Catalog Integration: Sync AAP resources into Backstage catalog
• Scaffolder Actions: Create software templates that interact with AAP
• Authentication: Integrate AAP authentication with Backstage auth
• RBAC Support: Leverage AAP's role-based access control
• Dynamic Plugin Support: Deploy as dynamic plugins in Red Hat Developer Hub
• Portal SDK: Shared frontend/backend contracts with native Blueprint contributions
• APME Integration: Quality views, scan actions, and repository registration workflows
• Configurable Navigation: Select discovered page links or expandable groups without changing permissions

Before setting up the development environment, ensure you have:

• Node.js: Version 22 or 24, matching the root package engines and CI matrix

  • Check version: node --version
  • Install via nvm or from nodejs.org

• Yarn: Version 4.12.0 (managed via Corepack, as pinned in package.json)

  • Install Corepack if your Node.js distribution does not include it
  • Enable Corepack: corepack enable
  • Verify: yarn --version

• Git: For version control

  • Check version: git --version

• Operating System: Linux, macOS, or Windows with WSL2
• RAM: Minimum 8GB (16GB recommended for optimal build performance)
• Disk Space: At least 2GB free space for dependencies and build artifacts

• Ansible Automation Platform: Access to an AAP instance for full functionality

  • Version 2.4 or later recommended
  • API access token with appropriate permissions

• GitHub Account: For GitHub integration features

  • Personal Access Token (PAT) with repo scope

1. Clone the Repository

git clone https://github.com/ansible/ansible-backstage-plugins.git
cd ansible-backstage-plugins

2. Install Dependencies

Enable Corepack and install the root Yarn workspace dependencies:

corepack enable
yarn install --immutable

The root packageManager field selects Yarn 4.12.0. Installation resolves all configured workspaces and runs the root Husky preparation script. Do not install each plugin separately or ignore dependency/native-build errors.

Alternatively, run ./install-deps, which will:

• Install all workspace dependencies
• Set up Git hooks via Husky (runs pre-commit from .pre-commit-config.yaml)
• Install the pre-commit CLI and prefetch hook environments (requires Python 3 + pip)

If you use only yarn install --immutable, install pre-commit manually: pip install pre-commit && pre-commit install-hooks.

3. Verify Installation

Check that installation was successful:

# Check Node.js version
node --version  # Should show v22.x.x or v24.x.x

# Check Yarn version
yarn --version  # Should show 4.12.0

# Verify workspace structure
yarn workspaces list

All secrets are managed via a .env file. It is loaded automatically by yarn start via dotenv-cli.

cp .env.example .env

Edit .env and fill in the required values:

Note: AUTH_SIGNING_KEY is auto-generated if left empty. Set it explicitly for stable configuration across restarts. Backend plugin-to-plugin authentication uses Backstage's built-in auth services without a shared secret. Configure backend.auth.externalAccess separately for external callers.

For local overrides (non-secret settings like schedule intervals, enabled features, etc.):

cp app-config.yaml app-config.local.yaml

Edit app-config.local.yaml to customize settings for your local environment. This file is gitignored.

Make sure you have created a .env file (see Configuration above), then:

yarn start

This will:

• Load environment variables from .env via dotenv-cli
• Auto-generate AUTH_SIGNING_KEY if not set
• Start the backend on http://localhost:7007
• Start the frontend on http://localhost:3000
• Enable hot module reloading for development
• Open your browser automatically

1. First Launch: Wait for frontend compilation and backend initialization
2. Browser Opens: Navigate to http://localhost:3000
3. Login: Use Guest login or configured auth provider
4. Hot Reload: Changes to source files automatically reload

Normal startup logs include:

[0] info: Loaded config from app-config.yaml, app-config.local.yaml
[0] info: Created database connection
[1] info: Listening on :7007
[0] webpack compiled successfully

The source app defaults to the new frontend system (NFS). Its user-facing routes include:

• Templates: http://localhost:3000/self-service (the default destination of / when installed and no landing override is configured)
• History: http://localhost:3000/self-service/create/tasks
• Execution Environments: http://localhost:3000/self-service/ee
• Collections: http://localhost:3000/self-service/collections
• Git repositories: http://localhost:3000/self-service/repositories
• Administration/RBAC: http://localhost:3000/rbac, subject to permissions
• Settings: http://localhost:3000/settings

Sidebar configuration selects installed page extensions; it does not install plugins or grant permissions. ?portalFrontend=legacy explicitly selects the legacy app. The local header retains account/logout controls. RHDH uses its platform header. The duplicate /portal/* pages have been removed. See Portal NFS composition for integration, navigation configuration, and verification boundaries. Backend port 7007 is the checked-in default; local configuration can override it.

ansible-backstage-plugins/
├── api/                       # OpenAPI spec and testing docs
│   ├── openapi.yaml          # API specification (source of truth)
│   └── README.md             # Swagger UI setup and testing guide
│
├── workspaces/                # Packages grouped by ownership
│   ├── portal-core/
│   │   ├── packages/app/      # Source frontend development harness
│   │   ├── packages/backend/  # Source backend development harness
│   │   └── plugins/           # Portal host, SDK, operations, and health
│   ├── self-service/plugins/  # Templates, tasks, and current content pages
│   ├── aap/plugins/           # AAP clients, authentication, catalog, actions
│   └── apme/plugins/          # Third-party contribution example and backend modules
│
├── docs/                      # Documentation
│   ├── features/             # Feature documentation
│   └── plugins/              # Plugin-specific docs
│
├── examples/                  # Example configurations
│   ├── entities.yaml         # Sample catalog entities
│   ├── org.yaml              # Sample organization structure
│   └── template/             # Sample software template
│
├── app-config.yaml           # Main configuration file
├── app-config.production.yaml # Production configuration
├── package.json              # Root package.json with workspaces
├── tsconfig.json             # TypeScript configuration
└── yarn.lock                 # Dependency lock file

The packages below include installable plugins/modules and shared libraries. A library does not create a page or sidebar item merely by being installed.

• @ansible/portal-core: native frontend host and configurable navigation.
• @ansible/portal-extension-api: frontend Blueprint contracts, API references, and clients.
• @ansible/portal-extension-common: shared manifest, launch, operation, and entitlement contracts.
• @ansible/portal-extension-host: contribution validation, filtering, and rendering.
• @ansible/portal-health-backend: backend health aggregation.
• @ansible/portal-operations-backend: authorized operations and host entitlement decisions.
• @ansible/portal-plugin-node: backend services, audit, health, and organization helpers.
• @ansible/portal-plugin-sdk: reusable frontend components, context, cache, notifications, and theme utilities.
• @ansible/portal-rhdh: optional native RHDH adapter for contributed profile-menu items, including AAP Sign out.

• @ansible/backstage-plugin-auth-backend-module-rhaap-provider: AAP authentication.
• @ansible/plugin-backstage-rhaap: existing AAP frontend integration.
• @ansible/backstage-rhaap-common: AAP/SCM clients, service contracts, types, and permissions.
• @ansible/backstage-plugin-catalog-backend-module-rhaap: AAP resource and content synchronization.
• @ansible/backstage-plugin-catalog-backend-module-rhaap-user-provisioner: on-demand catalog user provisioning.
• @ansible/plugin-scaffolder-backend-module-backstage-rhaap: AAP scaffolder actions.

• @ansible/portal-scaffolder: templates, tasks/history, native fields, and current collection/EE/repository pages awaiting content extraction.

• @ansible/plugin-backstage-apme: native Quality contributions and repository workflows.
• @ansible/backstage-apme-common: shared APME types, services, operations, and permissions.
• @ansible/backstage-plugin-catalog-backend-module-apme: catalog providers, operation handlers, settings, and synchronization.
• @ansible/scaffolder-backend-module-apme: repository-registration scaffolder action.

See the workspace overview for source ownership and the implementation guide for remaining architecture work.

The native source app defaults to the full contributor set. To test optional composition, set a preset in your uncommitted app-config.local.yaml:

portal:
  development:
    profile: core

full includes portal-scaffolder and APME; scaffolder omits APME; core omits both. AAP authentication, host services, Administration, and Settings remain available. Without a configured installed landing page, / shows the neutral Portal fallback. The global header has no Create shortcut. Use the installed pages and their page-level actions to start workflows. Existing content browsing pages still belong to portal-scaffolder; removing that contributor also removes those pages.

These presets are development/test conveniences, not production configuration, authorization policy, or a list of supported plugins. The explicit legacy frontend selector retains its existing composition.

To test another frontend plugin without changing the presets:

1. Register its package in the repository's Yarn workspaces. Give it the frontend-plugin or frontend-plugin-module Backstage role and a native ./alpha export. Its package root must be side-effect-free: declare "sideEffects": false and do not register legacy contributions there. Backstage discovery imports both the root and native entry; the declaration is an author contract, not a sandbox that prevents arbitrary module code.

2. Add the workspace dependency to the source app:

   yarn workspace app add '@ansible/plugin-example@workspace:^'

3. Include that package explicitly in your local configuration:

   portal:
     development:
       profile: core
   app:
     packages:
       include:
         - '@ansible/plugin-example'

4. Restart yarn start. The preflight rejects unknown packages, non-native frontend entries, dependencies resolving outside the selected workspace, and rediscovery of the preset-managed packages. Use explicit include, not all-package discovery. A new backend plugin still requires registration in the source backend; frontend discovery does not install backend services.

Verify the harness with yarn test:composition, yarn tsc, and the affected package's tests/lint. For dynamic frontend/backend exports on local RHDH, use the PORTAL_EXTRA_PLUGINS procedure in automation-portal-local's development guide. Production RHDH selects installed artifacts through its normal dynamic plugin configuration, not these source-app presets.

# Run all tests once
yarn test

# Run tests in watch mode
yarn test:watch

# Run tests with coverage
yarn test:all

# Test a specific plugin
yarn workspace @ansible/plugin-backstage-rhaap test

# Test with coverage
yarn workspace @ansible/plugin-backstage-rhaap test --coverage

• Maintain >80% code coverage for all plugins
• Coverage reports are generated in coverage/ directory
• View HTML report: open coverage/lcov-report/index.html
• CI publishes plugin-only coverage from all four workspace plugin roots; app/backend harness packages are excluded from that filtered report.

End-to-end tests use Playwright and are located in e2e-tests/.

# Install e2e dependencies
cd e2e-tests && yarn install

# Run all e2e tests
yarn pw:test

# Run e2e tests (self-service)
yarn pw:test:self-service

# Run e2e tests (RHDH)
yarn pw:test:rhdh

# View test report
yarn pw:show-report

• Codecov: codecov.io/gh/ansible/ansible-backstage-plugins
• SonarCloud: sonarcloud.io/project/overview?id=ansible_ansible-backstage-plugins
• Local HTML Report: After running yarn test:all, open coverage/lcov-report/index.html

# Type check
yarn tsc

# Build all packages
yarn build:all

Solution: Inspect the failing package's build log and resolve its platform prerequisites or permissions. Do not suppress an installation failure:

yarn install --immutable

Solution: Increase Node.js memory:

export NODE_OPTIONS="--max-old-space-size=16384"
yarn build:all

Solution: Either stop the conflicting process or use different ports:

# Inspect the listeners before stopping a confirmed application process
lsof -nP -iTCP:3000 -iTCP:7007 -sTCP:LISTEN

# Or configure different ports in app-config.local.yaml

Solution: For development, disable SSL verification:

aap:
  checkSSL: false

For production, ensure proper SSL certificates are configured.

Solution: Verify token has correct scopes:

# Test token
curl -H "Authorization: token YOUR_TOKEN" https://api.github.com/user

Required scopes: repo (private repos) or public_repo (public only)

Solution: Clear build cache and rebuild:

yarn clean
yarn install
yarn build:all
yarn start

Solution: Rebuild TypeScript declarations:

yarn tsc --build --clean
yarn tsc

If you encounter issues:

1. Check existing GitHub Issues
2. Review plugin-specific README files
3. Consult the Documentation
4. Ask in GitHub Discussions

• Installation Guide: Deployment instructions
• Features Overview: Comprehensive feature documentation
• Changelog: Release notes, breaking changes, and upgrade hints
• Portal NFS composition: Native plugin contracts, navigation, and acceptance scope
• Portal implementation guide: Current delivery scope and remaining architecture work

• OpenAPI Specification: Backend API spec, Swagger UI setup, and testing guide

Package references are linked in Available Plugins. The documentation site's Plugins tab groups them by Portal core/SDK, AAP, APME, and Self-service ownership.

• Native NFS composition
• Implementation and remaining architecture
• Content picker contract proposal
• Design tokens
• Quickstart — legacy compatibility example
• RHDH dynamic plugin deployment

Install the documentation dependencies into an isolated environment, including the mkdocs-ansible theme package, then build from the repository root:

uv run --no-project --with-requirements .config/requirements.txt mkdocs build --strict

If uv is unavailable, use a Python virtual environment and install .config/requirements.txt there before running python -m mkdocs build --strict. The Material social-card generator also requires Cairo shared-library discovery; an installed Python CairoSVG package alone is not sufficient.

• External Authentication
• Job Templates
• Users, Teams & Organizations

• Backstage Documentation

See CHANGELOG.md for version history, breaking changes (for example catalog sync route renames), and upgrade guidance for templates and integrations.

We welcome contributions! Please see our Contributing Guide for details on:

• Code of Conduct
• Development workflow
• Coding standards
• Pull request process
• Testing requirements

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests
5. Run yarn lint:all and yarn test:all
6. Submit a pull request

For information on how releases are managed, see RELEASE_PROCESS.md.

For information about reporting security vulnerabilities, see SECURITY.md.

This project is licensed under the Apache License 2.0. See LICENSE for details.

By contributing to this project, you agree that your contributions will be licensed under the Apache License 2.0.

This project is actively maintained by the Ansible team at Red Hat. We appreciate all contributions and feedback from the community!

• Issues: GitHub Issues
• Discussions: GitHub Discussions

Made with ❤️ by the Ansible team