Ansible Backstage Plugins

Welcome to the Ansible plugins for Backstage project! This repository provides plugins for backstage.io to deliver Ansible-specific user experiences in the developer portal, enabling self-service automation and integration with Ansible Automation Platform (AAP).

Table of Contents

• Overview
• Features
• Prerequisites
• Getting Started
  • Initial Setup
  • Configuration
  • Running Locally
• Repository Structure
• Available Plugins
• Development
  • Testing
  • Building
  • Plugin Development
• 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

This is a monorepo containing multiple plugins that work together to provide a comprehensive Ansible experience in Backstage.

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

Prerequisites

Before setting up the development environment, ensure you have:

Required Software

• Node.js: Version 20 or 22 (LTS versions)

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

• Yarn: Version 4.9.2 (managed via Corepack)

  • Corepack is included with Node.js 16.10+
  • 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

Run the installation script to set up all dependencies:

./install-deps

This script will:

• Install Yarn 4.x via Corepack
• Install all workspace dependencies
• Set up Git hooks via Husky for pre-commit checks

Note: On systems with strict security policies, some native package builds may fail. This is usually acceptable as they're often optional dependencies.

3. Verify Installation

Check that installation was successful:

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

# Check Yarn version
yarn --version  # Should show 4.9.1 or similar

# 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:

Variable	Required	Description
BACKEND_SECRET	No	Auto-generated on each yarn start if left empty
AUTH_SIGNING_KEY	No	Auto-generated on each yarn start if left empty
GITHUB_INTEGRATION_TOKEN	Yes	GitHub PAT for SCM integration (create here)
GITLAB_INTEGRATION_TOKEN	If using GitLab	GitLab PAT for SCM integration
AUTH_GITHUB_CLIENT_ID	If using GitHub auth	GitHub OAuth App client ID (create here)
AUTH_GITHUB_CLIENT_SECRET	If using GitHub auth	GitHub OAuth App client secret
AUTH_GITLAB_CLIENT_ID	If using GitLab auth	GitLab OAuth App client ID
AUTH_GITLAB_CLIENT_SECRET	If using GitLab auth	GitLab OAuth App client secret
AAP_HOST	Yes	AAP controller URL (e.g. https://aap.example.com)
AAP_AUTH_CLIENT_ID	Yes	AAP OAuth client ID
AAP_AUTH_CLIENT_SECRET	Yes	AAP OAuth client secret
AAP_API_TOKEN	Yes	AAP API token for catalog sync

Note: BACKEND_SECRET and AUTH_SIGNING_KEY are auto-generated if left empty. Set them explicitly if you need persistent sessions across restarts.

2. Create Local Configuration File (Optional)

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.

Running Locally

Start the Development Server

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 BACKEND_SECRET and 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

What to Expect

1. First Launch: Initial compilation takes 2-3 minutes
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

Startup Logs

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

Accessing Different Sections

• Home: http://localhost:3000
• Catalog: http://localhost:3000/catalog
• Ansible Plugin: http://localhost:3000/ansible
• Ansible Self-service Plugin: http://localhost:3000/self-service (AAP Related)
• API Docs: http://localhost:7007/api/docs

Repository Structure

ansible-backstage-plugins/
├── api/                       # OpenAPI spec and testing docs
│   ├── openapi.yaml          # API specification (source of truth)
│   └── README.md             # Swagger UI setup and testing guide
│
├── packages/                  # Core Backstage application
│   ├── app/                  # Frontend React application
│   └── backend/              # Backend Node.js service
│
├── plugins/                   # Ansible-specific plugins
│   ├── backstage-rhaap/                    # Provides access to the frontend plugin
│   ├── backstage-rhaap-common/             # Shared utilities and types
│   ├── auth-backend-module-rhaap-provider/ # Authentication provider
│   ├── catalog-backend-module-rhaap/       # Catalog integration
│   ├── scaffolder-backend-module-backstage-rhaap/ # Scaffolder actions
│   └── self-service/                       # Self-service UI plugin
│
├── 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

Available Plugins

Frontend Plugins

@ansible/plugin-backstage-rhaap

Enables the Ansible sidebar option and provides access to the frontend plugin

Features:

• Ansible specific UI
• Allows to view ansible specific catalog information
• Allows to view and run ansible specific software templates
• Ansible related learning paths.

@ansible/plugin-self-service

Self-service UI plugin for simplified automation access.

Features:

• Simplified job template interface
• Role-based view filtering
• Quick launch capabilities

Backend Plugins

@ansible/auth-backend-module-rhaap-provider

Authentication provider for integrating AAP authentication with Backstage.

@ansible/catalog-backend-module-rhaap

Catalog provider that syncs AAP resources into the Backstage catalog.

Syncs:

• Organizations
• Teams
• Users
• Projects
• Inventories

@ansible/scaffolder-backend-module-backstage-rhaap

Scaffolder actions for creating software templates that interact with AAP.

Actions:

• Launch job templates
• Create projects
• Manage inventories
• Configure credentials

Shared Packages

@ansible/plugin-backstage-rhaap-common

Shared utilities, types, and API clients used across all plugins.

Development

Testing

Run Unit Tests

# Run all tests once
yarn test

# Run tests in watch mode
yarn test:watch

# Run tests with coverage
yarn test:all

Test Specific Plugin

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

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

Coverage Requirements

• Maintain >80% code coverage for all plugins
• Coverage reports are generated in coverage/ directory
• View HTML report: open coverage/lcov-report/index.html

E2E Tests

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

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

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

# Run e2e tests (RHDH)
yarn e2e:rhdh

# Generate test reports
yarn report:generate

Viewing Coverage Reports

• 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

Building

Build All Packages

# Type check
yarn tsc

# Build all packages
yarn build:all

Troubleshooting

Common Issues and Solutions

Issue: yarn install fails with native package errors

Solution: Some native packages (like esbuild) may fail in restricted environments. This is usually acceptable:

yarn install --immutable || echo "Some optional dependencies failed, continuing..."

Issue: Out of memory during build

Solution: Increase Node.js memory:

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

Issue: Port 3000 or 7007 already in use

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

# Find process using port
lsof -ti:3000 | xargs kill -9  # macOS/Linux

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

Issue: AAP connection fails with SSL errors

Solution: For development, disable SSL verification:

aap:
  checkSSL: false

For production, ensure proper SSL certificates are configured.

Issue: GitHub integration not working

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)

Issue: Plugins not loading

Solution: Clear build cache and rebuild:

yarn clean
yarn install
yarn build:all
yarn start

Issue: TypeScript errors after updating dependencies

Solution: Rebuild TypeScript declarations:

yarn tsc --build --clean
yarn tsc

Getting Help

If you encounter issues:

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

Documentation

General Documentation

• Installation Guide: Deployment instructions
• Features Overview: Comprehensive feature documentation
• Changelog: Release notes, breaking changes, and upgrade hints

API Reference

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

Plugin Documentation

• Frontend Plugin: AAP frontend integration
• Self-Service Plugin: Simplified automation UI
• Auth Provider: AAP authentication
• Catalog Module: Catalog integration
• Scaffolder Module: Scaffolder actions

Feature Documentation

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

Additional Resources

• Backstage Documentation

Changelog

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

Contributing

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

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

Quick Start for Contributors

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

Release Process

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

Security

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

License

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.

Project Status

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

Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions

---

Made with ❤️ by the Ansible team