{"id":32891509,"url":"https://github.com/ansible/ansible-backstage-plugins","last_synced_at":"2026-06-11T15:00:29.444Z","repository":{"id":321073248,"uuid":"1071516449","full_name":"ansible/ansible-backstage-plugins","owner":"ansible","description":"Backstage plugins for Ansible","archived":false,"fork":false,"pushed_at":"2026-06-11T09:07:53.000Z","size":34101,"stargazers_count":6,"open_issues_count":21,"forks_count":20,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-06-11T10:07:47.545Z","etag":null,"topics":["ansible","automation","backstage","developer","developer-experience","idp"],"latest_commit_sha":null,"homepage":"https://ansible.github.io/ansible-backstage-plugins/","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ansible.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2025-10-07T13:04:36.000Z","updated_at":"2026-06-11T08:05:13.000Z","dependencies_parsed_at":null,"dependency_job_id":"242d20e0-eff2-4e54-92b7-e568a7e5c8ef","html_url":"https://github.com/ansible/ansible-backstage-plugins","commit_stats":null,"previous_names":["ansible/backstage-plugins-ansible","ansible/ansible-backstage-plugins"],"tags_count":28,"template":false,"template_full_name":null,"purl":"pkg:github/ansible/ansible-backstage-plugins","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ansible%2Fansible-backstage-plugins","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ansible%2Fansible-backstage-plugins/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ansible%2Fansible-backstage-plugins/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ansible%2Fansible-backstage-plugins/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ansible","download_url":"https://codeload.github.com/ansible/ansible-backstage-plugins/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ansible%2Fansible-backstage-plugins/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34204180,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-11T02:00:06.485Z","response_time":57,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ansible","automation","backstage","developer","developer-experience","idp"],"created_at":"2025-11-10T04:00:46.353Z","updated_at":"2026-06-11T15:00:29.399Z","avatar_url":"https://github.com/ansible.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Ansible Backstage Plugins\n\n[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)\n[![codecov](https://codecov.io/gh/ansible/ansible-backstage-plugins/graph/badge.svg)](https://codecov.io/gh/ansible/ansible-backstage-plugins)\n[![Coverage](https://sonarcloud.io/api/project_badges/measure?project=ansible_ansible-backstage-plugins\u0026metric=coverage)](https://sonarcloud.io/component_measures?id=ansible_ansible-backstage-plugins\u0026metric=coverage)\n\nWelcome to the Ansible plugins for Backstage project! This repository provides plugins for [backstage.io](https://backstage.io) to deliver Ansible-specific user experiences in the developer portal, enabling self-service automation and integration with Ansible Automation Platform (AAP).\n\n## Table of Contents\n\n- [Overview](#overview)\n- [Features](#features)\n- [Prerequisites](#prerequisites)\n- [Getting Started](#getting-started)\n  - [Initial Setup](#initial-setup)\n  - [Configuration](#configuration)\n  - [Running Locally](#running-locally)\n- [Repository Structure](#repository-structure)\n- [Available Plugins](#available-plugins)\n- [Development](#development)\n  - [Testing](#testing)\n  - [Building](#building)\n  - [Plugin Development](#plugin-development)\n- [Troubleshooting](#troubleshooting)\n- [Documentation](#documentation)\n- [Changelog](#changelog)\n- [Contributing](#contributing)\n- [Security](#security)\n- [License](#license)\n\n## Overview\n\nThe Ansible Backstage Plugins project brings Ansible Automation Platform capabilities into Backstage, enabling developers to:\n\n- Browse and launch job templates\n- Manage inventories, projects, and credentials\n- View job execution history and results\n- Create self-service automation workflows\n- Integrate AAP with software catalogs\n- Generate scaffolder actions for AAP resources\n\nThis is a monorepo containing multiple plugins that work together to provide a comprehensive Ansible experience in Backstage.\n\n## Features\n\n- **Frontend Integration**: Browse resources directly in Backstage UI\n- **Self-Service Automation**: Enable developers to trigger automations without AAP knowledge\n- **Catalog Integration**: Sync AAP resources into Backstage catalog\n- **Scaffolder Actions**: Create software templates that interact with AAP\n- **Authentication**: Integrate AAP authentication with Backstage auth\n- **RBAC Support**: Leverage AAP's role-based access control\n- **Dynamic Plugin Support**: Deploy as dynamic plugins in Red Hat Developer Hub\n\n## Prerequisites\n\nBefore setting up the development environment, ensure you have:\n\n### Required Software\n\n- **Node.js**: Version **20** or **22** (LTS versions)\n  - Check version: `node --version`\n  - Install via [nvm](https://github.com/nvm-sh/nvm) or from [nodejs.org](https://nodejs.org/)\n\n- **Yarn**: Version **4.9.2** (managed via Corepack)\n  - Corepack is included with Node.js 16.10+\n  - Enable Corepack: `corepack enable`\n  - Verify: `yarn --version`\n\n- **Git**: For version control\n  - Check version: `git --version`\n\n### System Requirements\n\n- **Operating System**: Linux, macOS, or Windows with WSL2\n- **RAM**: Minimum 8GB (16GB recommended for optimal build performance)\n- **Disk Space**: At least 2GB free space for dependencies and build artifacts\n\n### Optional But Recommended\n\n- **Ansible Automation Platform**: Access to an AAP instance for full functionality\n  - Version 2.4 or later recommended\n  - API access token with appropriate permissions\n\n- **GitHub Account**: For GitHub integration features\n  - Personal Access Token (PAT) with `repo` scope\n\n## Getting Started\n\n### Initial Setup\n\n1. **Clone the Repository**\n\n```bash\ngit clone https://github.com/ansible/ansible-backstage-plugins.git\ncd ansible-backstage-plugins\n```\n\n2. **Install Dependencies**\n\nRun the installation script to set up all dependencies:\n\n```bash\n./install-deps\n```\n\nThis script will:\n\n- Install Yarn 4.x via Corepack\n- Install all workspace dependencies\n- Set up Git hooks via Husky for pre-commit checks\n\n**Note**: On systems with strict security policies, some native package builds may fail. This is usually acceptable as they're often optional dependencies.\n\n3. **Verify Installation**\n\nCheck that installation was successful:\n\n```bash\n# Check Node.js version\nnode --version  # Should show v20.x.x or v22.x.x\n\n# Check Yarn version\nyarn --version  # Should show 4.9.1 or similar\n\n# Verify workspace structure\nyarn workspaces list\n```\n\n### Configuration\n\n#### 1. Create Environment File\n\nAll secrets are managed via a `.env` file. It is loaded automatically by `yarn start` via `dotenv-cli`.\n\n```bash\ncp .env.example .env\n```\n\nEdit `.env` and fill in the required values:\n\n| Variable                    | Required             | Description                                                                        |\n| --------------------------- | -------------------- | ---------------------------------------------------------------------------------- |\n| `BACKEND_SECRET`            | No                   | Auto-generated on each `yarn start` if left empty                                  |\n| `AUTH_SIGNING_KEY`          | No                   | Auto-generated on each `yarn start` if left empty                                  |\n| `GITHUB_INTEGRATION_TOKEN`  | Yes                  | GitHub PAT for SCM integration ([create here](https://github.com/settings/tokens)) |\n| `GITLAB_INTEGRATION_TOKEN`  | If using GitLab      | GitLab PAT for SCM integration                                                     |\n| `AUTH_GITHUB_CLIENT_ID`     | If using GitHub auth | GitHub OAuth App client ID ([create here](https://github.com/settings/developers)) |\n| `AUTH_GITHUB_CLIENT_SECRET` | If using GitHub auth | GitHub OAuth App client secret                                                     |\n| `AUTH_GITLAB_CLIENT_ID`     | If using GitLab auth | GitLab OAuth App client ID                                                         |\n| `AUTH_GITLAB_CLIENT_SECRET` | If using GitLab auth | GitLab OAuth App client secret                                                     |\n| `AAP_HOST`                  | Yes                  | AAP controller URL (e.g. `https://aap.example.com`)                                |\n| `AAP_AUTH_CLIENT_ID`        | Yes                  | AAP OAuth client ID                                                                |\n| `AAP_AUTH_CLIENT_SECRET`    | Yes                  | AAP OAuth client secret                                                            |\n| `AAP_API_TOKEN`             | Yes                  | AAP API token for catalog sync                                                     |\n\n**Note:** `BACKEND_SECRET` and `AUTH_SIGNING_KEY` are auto-generated if left empty. Set them explicitly if you need persistent sessions across restarts.\n\n#### 2. Create Local Configuration File (Optional)\n\nFor local overrides (non-secret settings like schedule intervals, enabled features, etc.):\n\n```bash\ncp app-config.yaml app-config.local.yaml\n```\n\nEdit `app-config.local.yaml` to customize settings for your local environment. This file is gitignored.\n\n### Running Locally\n\n#### Start the Development Server\n\nMake sure you have created a `.env` file (see [Configuration](#configuration) above), then:\n\n```bash\nyarn start\n```\n\nThis will:\n\n- Load environment variables from `.env` via `dotenv-cli`\n- Auto-generate `BACKEND_SECRET` and `AUTH_SIGNING_KEY` if not set\n- Start the backend on `http://localhost:7007`\n- Start the frontend on `http://localhost:3000`\n- Enable hot module reloading for development\n- Open your browser automatically\n\n#### What to Expect\n\n1. **First Launch**: Initial compilation takes 2-3 minutes\n2. **Browser Opens**: Navigate to `http://localhost:3000`\n3. **Login**: Use Guest login or configured auth provider\n4. **Hot Reload**: Changes to source files automatically reload\n\n#### Startup Logs\n\nNormal startup logs include:\n\n```\n[0] info: Loaded config from app-config.yaml, app-config.local.yaml\n[0] info: Created database connection\n[1] info: Listening on :7007\n[0] webpack compiled successfully\n```\n\n#### Accessing Different Sections\n\n- **Home**: `http://localhost:3000`\n- **Catalog**: `http://localhost:3000/catalog`\n- **Ansible Plugin**: `http://localhost:3000/ansible`\n- **Ansible Self-service Plugin**: `http://localhost:3000/self-service` (AAP Related)\n- **API Docs**: `http://localhost:7007/api/docs`\n\n## Repository Structure\n\n```\nansible-backstage-plugins/\n├── api/                       # OpenAPI spec and testing docs\n│   ├── openapi.yaml          # API specification (source of truth)\n│   └── README.md             # Swagger UI setup and testing guide\n│\n├── packages/                  # Core Backstage application\n│   ├── app/                  # Frontend React application\n│   └── backend/              # Backend Node.js service\n│\n├── plugins/                   # Ansible-specific plugins\n│   ├── backstage-rhaap/                    # Provides access to the frontend plugin\n│   ├── backstage-rhaap-common/             # Shared utilities and types\n│   ├── auth-backend-module-rhaap-provider/ # Authentication provider\n│   ├── catalog-backend-module-rhaap/       # Catalog integration\n│   ├── scaffolder-backend-module-backstage-rhaap/ # Scaffolder actions\n│   └── self-service/                       # Self-service UI plugin\n│\n├── docs/                      # Documentation\n│   ├── features/             # Feature documentation\n│   └── plugins/              # Plugin-specific docs\n│\n├── examples/                  # Example configurations\n│   ├── entities.yaml         # Sample catalog entities\n│   ├── org.yaml              # Sample organization structure\n│   └── template/             # Sample software template\n│\n├── app-config.yaml           # Main configuration file\n├── app-config.production.yaml # Production configuration\n├── package.json              # Root package.json with workspaces\n├── tsconfig.json             # TypeScript configuration\n└── yarn.lock                 # Dependency lock file\n```\n\n## Available Plugins\n\n### Frontend Plugins\n\n#### [@ansible/plugin-backstage-rhaap](./plugins/backstage-rhaap)\n\nEnables the Ansible sidebar option and provides access to the frontend plugin\n\n**Features**:\n\n- Ansible specific UI\n- Allows to view ansible specific catalog information\n- Allows to view and run ansible specific software templates\n- Ansible related learning paths.\n\n#### [@ansible/plugin-self-service](./plugins/self-service)\n\nSelf-service UI plugin for simplified automation access.\n\n**Features**:\n\n- Simplified job template interface\n- Role-based view filtering\n- Quick launch capabilities\n\n### Backend Plugins\n\n#### [@ansible/auth-backend-module-rhaap-provider](./plugins/auth-backend-module-rhaap-provider)\n\nAuthentication provider for integrating AAP authentication with Backstage.\n\n#### [@ansible/catalog-backend-module-rhaap](./plugins/catalog-backend-module-rhaap)\n\nCatalog provider that syncs AAP resources into the Backstage catalog.\n\n**Syncs**:\n\n- Organizations\n- Teams\n- Users\n- Projects\n- Inventories\n\n#### [@ansible/scaffolder-backend-module-backstage-rhaap](./plugins/scaffolder-backend-module-backstage-rhaap)\n\nScaffolder actions for creating software templates that interact with AAP.\n\n**Actions**:\n\n- Launch job templates\n- Create projects\n- Manage inventories\n- Configure credentials\n\n### Shared Packages\n\n#### [@ansible/plugin-backstage-rhaap-common](./plugins/backstage-rhaap-common)\n\nShared utilities, types, and API clients used across all plugins.\n\n## Development\n\n### Testing\n\n#### Run Unit Tests\n\n```bash\n# Run all tests once\nyarn test\n\n# Run tests in watch mode\nyarn test:watch\n\n# Run tests with coverage\nyarn test:all\n```\n\n#### Test Specific Plugin\n\n```bash\n# Test a specific plugin\nyarn workspace @ansible/plugin-backstage-rhaap test\n\n# Test with coverage\nyarn workspace @ansible/plugin-backstage-rhaap test --coverage\n```\n\n#### Coverage Requirements\n\n- Maintain \u003e80% code coverage for all plugins\n- Coverage reports are generated in `coverage/` directory\n- View HTML report: `open coverage/lcov-report/index.html`\n\n#### E2E Tests\n\nEnd-to-end tests use Cypress and are located in `e2e-tests/`.\n\n```bash\n# Install e2e dependencies\ncd e2e-tests \u0026\u0026 yarn install\n\n# Run e2e tests (self-service)\nyarn e2e:self-service\n\n# Run e2e tests (RHDH)\nyarn e2e:rhdh\n\n# Generate test reports\nyarn report:generate\n```\n\n#### Viewing Coverage Reports\n\n- **Codecov**: [codecov.io/gh/ansible/ansible-backstage-plugins](https://codecov.io/gh/ansible/ansible-backstage-plugins)\n- **SonarCloud**: [sonarcloud.io/project/overview?id=ansible_ansible-backstage-plugins](https://sonarcloud.io/project/overview?id=ansible_ansible-backstage-plugins)\n- **Local HTML Report**: After running `yarn test:all`, open `coverage/lcov-report/index.html`\n\n### Building\n\n#### Build All Packages\n\n```bash\n# Type check\nyarn tsc\n\n# Build all packages\nyarn build:all\n```\n\n## Troubleshooting\n\n### Common Issues and Solutions\n\n#### Issue: `yarn install` fails with native package errors\n\n**Solution**: Some native packages (like `esbuild`) may fail in restricted environments. This is usually acceptable:\n\n```bash\nyarn install --immutable || echo \"Some optional dependencies failed, continuing...\"\n```\n\n#### Issue: Out of memory during build\n\n**Solution**: Increase Node.js memory:\n\n```bash\nexport NODE_OPTIONS=\"--max-old-space-size=16384\"\nyarn build:all\n```\n\n#### Issue: Port 3000 or 7007 already in use\n\n**Solution**: Either stop the conflicting process or use different ports:\n\n```bash\n# Find process using port\nlsof -ti:3000 | xargs kill -9  # macOS/Linux\n\n# Or configure different ports in app-config.local.yaml\n```\n\n#### Issue: AAP connection fails with SSL errors\n\n**Solution**: For development, disable SSL verification:\n\n```yaml\naap:\n  checkSSL: false\n```\n\n**For production**, ensure proper SSL certificates are configured.\n\n#### Issue: GitHub integration not working\n\n**Solution**: Verify token has correct scopes:\n\n```bash\n# Test token\ncurl -H \"Authorization: token YOUR_TOKEN\" https://api.github.com/user\n```\n\nRequired scopes: `repo` (private repos) or `public_repo` (public only)\n\n#### Issue: Plugins not loading\n\n**Solution**: Clear build cache and rebuild:\n\n```bash\nyarn clean\nyarn install\nyarn build:all\nyarn start\n```\n\n#### Issue: TypeScript errors after updating dependencies\n\n**Solution**: Rebuild TypeScript declarations:\n\n```bash\nyarn tsc --build --clean\nyarn tsc\n```\n\n### Getting Help\n\nIf you encounter issues:\n\n1. Check existing [GitHub Issues](https://github.com/ansible/ansible-backstage-plugins/issues)\n2. Review plugin-specific README files\n3. Consult the [Documentation](#documentation)\n4. Ask in [GitHub Discussions](https://github.com/ansible/ansible-backstage-plugins/discussions)\n\n## Documentation\n\n### General Documentation\n\n- **[Installation Guide](./docs/installation.md)**: Deployment instructions\n- **[Features Overview](./docs/index.md)**: Comprehensive feature documentation\n- **[Changelog](./CHANGELOG.md)**: Release notes, breaking changes, and upgrade hints\n\n### API Reference\n\n- **[OpenAPI Specification](./api/README.md)**: Backend API spec, Swagger UI setup, and testing guide\n\n### Plugin Documentation\n\n- **[Frontend Plugin](./docs/plugins/backstage-frontend.md)**: AAP frontend integration\n- **[Self-Service Plugin](./docs/plugins/self-service.md)**: Simplified automation UI\n- **[Auth Provider](./docs/plugins/auth.md)**: AAP authentication\n- **[Catalog Module](./docs/plugins/catalog.md)**: Catalog integration\n- **[Scaffolder Module](./docs/plugins/scaffolder.md)**: Scaffolder actions\n\n### Feature Documentation\n\n- **[External Authentication](./docs/features/external-authentication.md)**\n- **[Job Templates](./docs/features/job-templates.md)**\n- **[Users, Teams \u0026 Organizations](./docs/features/users-teams-organizations.md)**\n\n### Additional Resources\n\n- [Backstage Documentation](https://backstage.io/docs/)\n\n## Changelog\n\nSee **[CHANGELOG.md](./CHANGELOG.md)** for version history, **breaking changes** (for example catalog sync route renames), and upgrade guidance for templates and integrations.\n\n## Contributing\n\nWe welcome contributions! Please see our [Contributing Guide](./CONTRIBUTING.md) for details on:\n\n- Code of Conduct\n- Development workflow\n- Coding standards\n- Pull request process\n- Testing requirements\n\n### Quick Start for Contributors\n\n1. Fork the repository\n2. Create a feature branch\n3. Make your changes\n4. Add tests\n5. Run `yarn lint:all` and `yarn test:all`\n6. Submit a pull request\n\n### Release Process\n\nFor information on how releases are managed, see [RELEASE_PROCESS.md](./RELEASE_PROCESS.md).\n\n## Security\n\nFor information about reporting security vulnerabilities, see [SECURITY.md](./SECURITY.md).\n\n## License\n\nThis project is licensed under the **Apache License 2.0**. See [LICENSE](./LICENSE) for details.\n\nBy contributing to this project, you agree that your contributions will be licensed under the Apache License 2.0.\n\n## Project Status\n\nThis project is actively maintained by the Ansible team at Red Hat. We appreciate all contributions and feedback from the community!\n\n## Support\n\n- **Issues**: [GitHub Issues](https://github.com/ansible/ansible-backstage-plugins/issues)\n- **Discussions**: [GitHub Discussions](https://github.com/ansible/ansible-backstage-plugins/discussions)\n\n---\n\nMade with ❤️ by the Ansible team\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fansible%2Fansible-backstage-plugins","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fansible%2Fansible-backstage-plugins","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fansible%2Fansible-backstage-plugins/lists"}