Ansible Backstage Plugins

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.

Table of Contents

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

Overview

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.

Features

• 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

Prerequisites

Before setting up the development environment, ensure you have:

Required Software

• 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

System Requirements

• 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

Optional But Recommended

• 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

Getting Started

Initial Setup

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

Configuration

1. Create Environment File

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:

This is the beginning of the README. Read the rest at the original. Read the full README ↗