### Example Backstage Backend Setup with SpectroCloud Auth (TypeScript)

Source: https://terasky-oss.github.io/backstage-plugins/plugins/spectrocloud/auth/backend/install

An example demonstrating how to integrate the SpectroCloud authentication module within a Backstage backend setup. It includes adding the core auth backend and the SpectroCloud specific module.

```typescript
import {
  createBackend,
} from '@backstage/backend-defaults';

const backend = createBackend();

// Required: Core auth backend
backend.add(import('@backstage/plugin-auth-backend'));

// Add SpectroCloud auth module
backend.add(import('@terasky/backstage-plugin-spectrocloud-auth-backend'));

// ... other plugins

backend.start();
```

--------------------------------

### Start Backstage Development Server

Source: https://terasky-oss.github.io/backstage-plugins/plugins/api-docs-module-crd/frontend/install

Command to launch the Backstage development environment to verify the installation.

```shell
yarn dev
```

--------------------------------

### Full Configuration Examples

Source: https://terasky-oss.github.io/backstage-plugins/plugins/spectrocloud/auth/kubernetes-module/configure

Comprehensive examples covering SpectroCloud-only setups, mixed authentication methods (OIDC and service accounts), multi-tenant environments, and multi-provider OIDC configurations.

```yaml
# Example 1: SpectroCloud-Only
auth:
  providers:
    spectrocloud:
      development:
        clientId: ${SPECTROCLOUD_CLIENT_ID}
        clientSecret: ${SPECTROCLOUD_CLIENT_SECRET}
        authorizationUrl: https://console.spectrocloud.com/v1/oidc/tenant/abc123/auth
        signIn:
          resolvers:
            - resolver: emailMatchingUserEntityProfileEmail

spectrocloud:
  environments:
    - url: https://console.spectrocloud.com
      tenant: abc123
      apiToken: ${SPECTROCLOUD_API_TOKEN}
      clusterProvider:
        authType: oidc
        oidcAuthProviderName: spectrocloud
```

```yaml
# Example 2: Mixed Authentication
kubernetes:
  clusterLocatorMethods:
    - type: 'config'
      clusters:
        - name: legacy-prod
          url: https://legacy.example.com:6443
          authProvider: 'serviceAccount'
          serviceAccountToken: ${LEGACY_SA_TOKEN}
          skipTLSVerify: true
        - name: new-prod
          url: https://new.example.com:6443
          authProvider: 'oidc'
          oidcTokenProvider: 'spectrocloud'
          skipTLSVerify: true

spectrocloud:
  environments:
    - url: https://console.spectrocloud.com
      tenant: my-tenant
      apiToken: ${SPECTROCLOUD_API_TOKEN}
      clusterProvider:
        authType: oidc
        includeProjects: [production]
```

```yaml
# Example 3: Multi-Tenant SpectroCloud
spectrocloud:
  environments:
    - name: us
      url: https://api-us.spectrocloud.com
      tenant: us-tenant
      apiToken: ${SPECTROCLOUD_US_TOKEN}
      clusterProvider:
        authType: oidc
        includeProjects: [production]
    - name: eu
      url: https://api-eu.spectrocloud.com
      tenant: eu-tenant
      apiToken: ${SPECTROCLOUD_EU_TOKEN}
      clusterProvider:
        authType: serviceAccount
        includeProjects: [production]
```

```yaml
# Example 4: Multi-Provider OIDC
kubernetes:
  clusterLocatorMethods:
    - type: 'config'
      clusters:
        - name: spectro-managed
          url: https://spectro.example.com:6443
          authProvider: 'oidc'
          oidcTokenProvider: 'spectrocloud'
        - name: gke-cluster
          url: https://gke.example.com:6443
          authProvider: 'oidc'
          oidcTokenProvider: 'google'
        - name: aks-cluster
          url: https://aks.example.com:6443
          authProvider: 'oidc'
          oidcTokenProvider: 'microsoft'
```

--------------------------------

### Start Backstage Backend (Yarn)

Source: https://terasky-oss.github.io/backstage-plugins/plugins/ai-rules-plugin/backend/install

Starts the Backstage backend development server using yarn. This command is used to verify the installation and observe backend logs for plugin registration.

```bash
yarn dev

```

--------------------------------

### Verify Plugin Logs

Source: https://terasky-oss.github.io/backstage-plugins/plugins/spectrocloud/cluster-provider/install

Example log output indicating successful cluster discovery and RBAC creation.

```text
SpectroCloud: Discovered X clusters
SpectroCloud: Created RBAC for cluster Y
```

--------------------------------

### Debug Backend Startup

Source: https://terasky-oss.github.io/backstage-plugins/plugins/crossplane/backend/install

Starts the backend service in verbose mode to troubleshoot initialization issues or plugin loading errors.

```shell
yarn workspace backend start --verbose
```

--------------------------------

### Start Backstage Backend Verbose for Troubleshooting

Source: https://terasky-oss.github.io/backstage-plugins/plugins/kubernetes/backend/install

Starts the Backstage backend in verbose mode to aid in troubleshooting startup issues. This command helps in identifying errors during the backend initialization process.

```bash
# Check backend logs
yarn workspace backend start --verbose
```

--------------------------------

### Configure VM Power Management Permissions

Source: https://terasky-oss.github.io/backstage-plugins/plugins/vcf/automation/frontend/install

Example of how to integrate the VM power management permission into a Backstage permission policy. It requires importing the permission object and defining the authorization result.

```typescript
import { vmPowerManagementPermission } from '@terasky/backstage-plugin-vcf-automation-common';

// In your permission policy:
{
  permission: vmPowerManagementPermission,
  result: AuthorizeResult.ALLOW, // or implement conditional logic as needed
}
```

--------------------------------

### Verify VCFA VKS Cluster Discovery Logs

Source: https://terasky-oss.github.io/backstage-plugins/plugins/vcf/automation/vks-cluster-provider/install

Example log output confirming that the plugin has successfully discovered and configured VKS clusters from the VCFA instance.

```text
Found X VKS cluster(s) in VCFA
VKS cluster refresh complete: X/X cluster(s) configured
✓ my-cluster (Service Account)
```

--------------------------------

### SpectroCloud Plugin Configuration Examples

Source: https://terasky-oss.github.io/backstage-plugins/plugins/spectrocloud/ingestor/configure

A collection of YAML configuration patterns for the SpectroCloud ingestor, ranging from basic setups to complex multi-instance and resource-specific filtering configurations.

```yaml
spectrocloud:
  annotationPrefix: terasky.backstage.io
  environments:
    - name: production
      url: https://api.spectrocloud.com
      tenant: my-tenant
      apiToken: ${SPECTROCLOUD_API_TOKEN}
      catalogProvider:
        enabled: true
        refreshIntervalSeconds: 600
        defaultOwner: spectrocloud-auto-ingested
        ownerNamespace: group
        includeProjects: [production, staging]
        excludeProjects: [sandbox]
        excludeTenantScopedResources: false
        resources:
          projects: true
          clusterProfiles: true
          clusters: true
          clusterGroups: true
          virtualClusters: true
```

```yaml
spectrocloud:
  environments:
    - url: https://api.spectrocloud.com
      tenant: my-tenant
      apiToken: ${SPECTROCLOUD_API_TOKEN}
      catalogProvider:
        enabled: true
```

```yaml
spectrocloud:
  environments:
    - name: prod
      url: https://api.spectrocloud.com
      tenant: my-tenant
      apiToken: ${SPECTROCLOUD_API_TOKEN}
      catalogProvider:
        enabled: true
        refreshIntervalSeconds: 300
        includeProjects: [production, staging]
        excludeProjects: [development, sandbox]
```

```yaml
spectrocloud:
  annotationPrefix: terasky.backstage.io
  environments:
    - name: us-prod
      url: https://api-us.spectrocloud.com
      tenant: us-tenant
      apiToken: ${SPECTROCLOUD_US_TOKEN}
      catalogProvider:
        enabled: true
        refreshIntervalSeconds: 600
        includeProjects: [us-production]
    - name: eu-prod
      url: https://api-eu.spectrocloud.com
      tenant: eu-tenant
      apiToken: ${SPECTROCLOUD_EU_TOKEN}
      catalogProvider:
        enabled: true
        refreshIntervalSeconds: 600
        includeProjects: [eu-production]
```

```yaml
spectrocloud:
  environments:
    - url: https://api.spectrocloud.com
      tenant: my-tenant
      apiToken: ${SPECTROCLOUD_API_TOKEN}
      catalogProvider:
        enabled: true
        resources:
          projects: false
          clusterProfiles: false
          clusters: true
          clusterGroups: false
          virtualClusters: false
```

--------------------------------

### Installation Steps

Source: https://terasky-oss.github.io/backstage-plugins/plugins/ai-rules-plugin/backend/install

Steps to install and integrate the AI Coding Rules backend plugin into your Backstage instance.

```APIDOC
## Installation Steps

### 1. Add the Package

Install the plugin package using yarn:

```bash
yarn --cwd packages/backend add @terasky/backstage-plugin-ai-rules-backend
```

### 2. Add to Backend

Add the plugin to your backend in `packages/backend/src/index.ts`:

```typescript
import { createBackend } from '@backstage/backend-defaults';

const backend = createBackend();

// ... other plugins
backend.add(import('@terasky/backstage-plugin-ai-rules-backend'));

backend.start();
```

### 3. Configure SCM Integrations

Ensure your SCM integrations are properly configured in `app-config.yaml`:

```yaml
integrations:
  github:
    - host: github.com
      token: ${GITHUB_TOKEN}

  gitlab:
    - host: gitlab.com
      token: ${GITLAB_TOKEN}

  # Add other SCM integrations as needed
```
```

--------------------------------

### Define Software Template with Spring Initializer

Source: https://terasky-oss.github.io/backstage-plugins/plugins/spring-initializer/frontend/install

Example of a Backstage software template YAML file utilizing the SpringInitializer UI field and the terasky:spring-initializer scaffolder action.

```yaml
apiVersion: scaffolder.backstage.io/v1beta3
kind: Template
metadata:
  name: spring-boot-template
  title: Spring Boot Application
  description: Create a new Spring Boot application
spec:
  type: service
  parameters:
    - title: Spring Boot Configuration
      properties:
        springConfig:
          title: Spring Configuration
          type: object
          ui:field: SpringInitializer
    - title: Repository Location
      required:
        - repoUrl
      properties:
        repoUrl:
          title: Repository Location
          type: string
          ui:field: RepoUrlPicker
          ui:options:
            allowedHosts:
              - github.com
  steps:
    - id: generate-spring
      name: Generate Spring Boot Project
      action: terasky:spring-initializer
      input:
        type: ${{ parameters.springConfig.type }}
        language: ${{ parameters.springConfig.language }}
        bootVersion: ${{ parameters.springConfig.bootVersion }}
        groupId: ${{ parameters.springConfig.groupId }}
        artifactId: ${{ parameters.springConfig.artifactId }}
        name: ${{ parameters.springConfig.name }}
        description: ${{ parameters.springConfig.description }}
        packageName: ${{ parameters.springConfig.packageName }}
        packaging: ${{ parameters.springConfig.packaging }}
        javaVersion: ${{ parameters.springConfig.javaVersion }}
        dependencies: ${{ parameters.springConfig.dependencies }}
    - id: publish
      name: Publish to Repository  
      action: publish:github
      input:
        description: ${{ parameters.springConfig.description }}
        repoUrl: ${{ parameters.repoUrl }}
        defaultBranch: main
```

--------------------------------

### Example Backstage Component Entity with Source Location Annotation (YAML)

Source: https://terasky-oss.github.io/backstage-plugins/plugins/ai-rules-plugin/frontend/install

Provides an example of a Backstage `Component` entity definition in YAML format, including the essential `backstage.io/source-location` annotation required for the AI Coding Rules plugin to identify the source repository.

```yaml
apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
  name: my-service
  annotations:
    backstage.io/source-location: url:https://github.com/org/repo
spec:
  type: service
  lifecycle: production
  owner: team-a
```

--------------------------------

### VCF Operations Plugin Initialization Log Message

Source: https://terasky-oss.github.io/backstage-plugins/plugins/vcf/operations/backend/install

Example log message indicating the successful initialization of the VCF Operations plugin and its registered permissions within the Backstage backend.

```log
[vcf-operations] VcfOperationsService initialized with 1 instance(s)
[vcf-operations] Permissions registered: vcf-operations.metrics.view

```

--------------------------------

### Get SpectroCloud Auth API and Profile (JavaScript)

Source: https://terasky-oss.github.io/backstage-plugins/plugins/spectrocloud/auth/frontend/install

Demonstrates how to retrieve the SpectroCloud authentication API reference and fetch the user's profile after successful sign-in within the Backstage browser console.

```javascript
// After signing in
const authApi = await window.backstage.getApi('core.auth.spectrocloud');
const profile = await authApi.getProfile();
console.log(profile);
```

--------------------------------

### Install Educates Backend Plugin via Yarn

Source: https://terasky-oss.github.io/backstage-plugins/plugins/educates/backend/install

Installs the required backend plugin package into the Backstage project using the yarn package manager.

```shell
yarn --cwd packages/backend add @terasky/backstage-plugin-educates-backend
```

--------------------------------

### Install KRO Resources Frontend Plugin (Yarn)

Source: https://terasky-oss.github.io/backstage-plugins/plugins/kro/frontend/install

Installs the KRO Resources Frontend plugin package using Yarn. This command should be run from the root directory of your Backstage application.

```bash
# From your Backstage root directory
yarn --cwd packages/app add @terasky/backstage-plugin-kro-resources-frontend

```

--------------------------------

### Install Educates Frontend Plugin Package with Yarn

Source: https://terasky-oss.github.io/backstage-plugins/plugins/educates/frontend/install

Installs the Educates frontend plugin package using yarn. This command is executed within the Backstage application's package directory.

```bash
yarn --cwd packages/app add @terasky/backstage-plugin-educates
```

--------------------------------

### Install All Peer Dependencies (Yarn)

Source: https://terasky-oss.github.io/backstage-plugins/plugins/spectrocloud/auth/frontend/install

Installs all peer dependencies for the Backstage project using Yarn. This is crucial for resolving import errors, especially when dealing with plugin compatibility and versioning.

```bash
yarn install
```

--------------------------------

### Install VCF SSO Frontend Package

Source: https://terasky-oss.github.io/backstage-plugins/plugins/vcf/sso/frontend/install

Installs the VCF SSO authentication frontend package into the Backstage application directory using Yarn.

```bash
yarn --cwd packages/app add @terasky/backstage-plugin-vcfsso-auth
```

--------------------------------

### Verify Plugin Installation

Source: https://terasky-oss.github.io/backstage-plugins/plugins/vcf/operations/frontend/install

Commands to verify the installation of the plugin packages and troubleshoot missing component errors.

```shell
yarn list @terasky/backstage-plugin-vcf-operations
yarn list @terasky/backstage-plugin-vcf-operations-common

yarn cache clean
yarn install
```

--------------------------------

### Install VCF Automation Plugin Package

Source: https://terasky-oss.github.io/backstage-plugins/plugins/vcf/automation/backend/install

Installs the required backend plugin package into the Backstage project using the Yarn package manager.

```bash
yarn --cwd packages/backend add @terasky/backstage-plugin-vcf-automation-backend
```

--------------------------------

### Install SpectroCloud Auth Plugin (Yarn)

Source: https://terasky-oss.github.io/backstage-plugins/plugins/spectrocloud/auth/frontend/install

Installs the SpectroCloud authentication frontend plugin package into the Backstage application using Yarn. This is the first step in integrating SpectroCloud authentication.

```bash
yarn --cwd packages/app add @terasky/backstage-plugin-spectrocloud-auth
```

--------------------------------

### Comprehensive Backstage Authentication Configuration Example

Source: https://terasky-oss.github.io/backstage-plugins/plugins/signin-page/frontend/configure

A complete example of the `app-config.yaml` file demonstrating various authentication providers (Microsoft, GitHub, GitLab, Google, Okta, etc.) with their respective enabled states, titles, and messages. It also includes comments explaining the purpose of each setting and best practices like disabling guest access in production.

```yaml
# app-config.yaml
signinPage:
  # Enable guest access for development (disable in production)
  enableGuestProvider: true

  providers:
    # Corporate primary authentication
    microsoft:
      enabled: true
      title: TeraSky SSO
      message: Sign in with your TeraSky Microsoft account

    # GitHub for open source contributors
    github:
      enabled: true
      title: GitHub
      message: External contributors - sign in with GitHub

    # GitLab for specific teams
    gitlab:
      enabled: true
      title: GitLab
      message: Engineering teams - sign in with GitLab

    # Google OAuth
    google:
      enabled: false  # Currently disabled
      title: Google
      message: Sign in using Google

    # Enterprise SSO providers
    okta:
      enabled: true
      title: Okta SSO
      message: Enterprise users - sign in with Okta

    # Other providers (disabled by default)
    onelogin:
      enabled: false

    openshift:
      enabled: false

    atlassian:
      enabled: false

    bitbucket:
      enabled: false

    bitbucketServer:
      enabled: false

    vmwareCloud:
      enabled: false

    spectrocloud:
      enabled: false

    vcfsso:
      enabled: false

```

--------------------------------

### Install CRD Module Package

Source: https://terasky-oss.github.io/backstage-plugins/plugins/api-docs-module-crd/frontend/install

Installs the CRD API Docs module package into the Backstage application using Yarn workspaces.

```shell
yarn workspace app add @terasky/backstage-plugin-api-docs-module-crd
```

--------------------------------

### Development and Production Configuration Examples

Source: https://terasky-oss.github.io/backstage-plugins/plugins/vcf/sso/frontend/configure

Provides examples for setting up VCF SSO in development and production environments, including guest access toggles.

```yaml
# Development Setup
auth:
  environment: development

signinPage:
  enableGuestProvider: true
  providers:
    vcfsso:
      enabled: true
      title: VCF SSO (Dev)
      message: Development — sign in with your VCF SSO account

# Production Setup
auth:
  environment: production

signinPage:
  enableGuestProvider: false
  providers:
    vcfsso:
      enabled: true
      title: VCF SSO
      message: Sign in with your corporate VCF SSO account
```

--------------------------------

### Get All Entities by Kind and Type

Source: https://terasky-oss.github.io/backstage-plugins/plugins/catalog-mcp/backend/configure

Fetches all entities that match a specific kind and type. This allows for precise filtering, for example, to find all 'service' components.

```json
{
  "action": "get_all_entities_by_kind_and_type",
  "input": {
    "kind": "Component",
    "type": "service"
  }
}
```

--------------------------------

### Configure Environment Variables

Source: https://terasky-oss.github.io/backstage-plugins/plugins/educates/backend/install

Defines the necessary credentials for the Educates training portal within the .env file.

```bash
EDUCATES_EXAMPLE_ROBOT_PASSWORD=your-robot-password
EDUCATES_EXAMPLE_ROBOT_CLIENT_ID=your-client-id
EDUCATES_EXAMPLE_ROBOT_CLIENT_SECRET=your-client-secret
```

--------------------------------

### Verify Plugin Installation via API

Source: https://terasky-oss.github.io/backstage-plugins/plugins/educates/backend/install

Uses curl commands to verify the plugin health and list configured training portals.

```shell
curl http://localhost:7007/api/educates/health
curl http://localhost:7007/api/educates/workshops/<TRAINING PORTAL NAME>/
```

--------------------------------

### Scaffolder Field Extensions Integration

Source: https://terasky-oss.github.io/backstage-plugins/plugins/gitops-manifest-updater/frontend/configure

Configuration examples for adding the GitOpsManifestUpdaterExtension to the Scaffolder. Includes both a basic setup and an advanced configuration with custom validation and PR creation logic.

```JSX
<ScaffolderFieldExtensions>
  <GitOpsManifestUpdaterExtension />
</ScaffolderFieldExtensions>
```

```JSX
<ScaffolderFieldExtensions>
  <GitOpsManifestUpdaterExtension
    defaultBranch="develop"
    defaultPath="k8s/"
    schemaValidator={customValidator}
    pullRequestCreator={customPRCreator}
  />
</ScaffolderFieldExtensions>
```

--------------------------------

### Troubleshoot Backend Startup Issues (Verbose)

Source: https://terasky-oss.github.io/backstage-plugins/plugins/spectrocloud/ingestor/install

Runs the Backstage backend with verbose logging enabled to help diagnose startup issues. This command is useful for identifying specific errors during the backend initialization process.

```bash
yarn workspace backend start --verbose

```

--------------------------------

### List Available Permissions

Source: https://terasky-oss.github.io/backstage-plugins/plugins/rbac-mcp/backend/usage

Discover all permissions from installed plugins. This action can optionally filter permissions by a specific plugin ID.

```json
{
  "action": "list_available_permissions"
}
```

```json
{
  "action": "list_available_permissions",
  "input": {
    "pluginId": "catalog"
  }
}
```

--------------------------------

### Scaffolder Action Usage Example

Source: https://terasky-oss.github.io/backstage-plugins/plugins/spring-initializer/backend/about

A YAML configuration example for integrating the terasky:spring-initializer action into a Backstage software template.

```yaml
steps:
  - id: generate-spring
    name: Generate Spring Boot Project
    action: terasky:spring-initializer
    input:
      type: maven-project
      language: java
      bootVersion: '3.5.10'
      groupId: com.example
      artifactId: myapp
      name: My Application
      description: My Spring Boot application
      packageName: com.example.myapp
      packaging: jar
      javaVersion: '17'
      dependencies: web,data-jpa,postgresql,actuator
      outputPath: .
```

--------------------------------

### API Response Example for AI Coding Rules

Source: https://terasky-oss.github.io/backstage-plugins/plugins/ai-rules-plugin/backend/about

This JSON structure represents the response from the GET /api/ai-rules/rules endpoint, detailing fetched AI coding rules, their types, file paths, content, and associated metadata. It includes examples for 'cursor' and 'roo-code' rule types.

```json
{
  "rules": [
    {
      "type": "cursor",
      "id": "cursor-rule-1",
      "filePath": ".cursor/rules/typescript.mdc",
      "fileName": "typescript",
      "content": "TypeScript coding standards...",
      "description": "TypeScript rules",
      "globs": ["*.ts", "*.tsx"],
      "alwaysApply": true,
      "gitUrl": "https://github.com/org/repo"
    },
    {
      "type": "roo-code",
      "id": "roo-code-rule-1",
      "filePath": ".roo/rules-code/standards.md",
      "fileName": "standards",
      "content": "...",
      "mode": "code",
      "gitUrl": "https://github.com/org/repo"
    }
  ],
  "totalCount": 2,
  "ruleTypes": ["cursor", "roo-code"]
}
```

--------------------------------

### Configure Educates Plugin in app-config.yaml

Source: https://terasky-oss.github.io/backstage-plugins/plugins/educates/backend/install

Sets up the training portal connection details and references environment variables for secure credential management.

```yaml
educates:
  trainingPortals:
    - name: example-portal
      url: https://example-training-portal.com
      robotUsername: robot@educates
      robotPassword: ${EDUCATES_EXAMPLE_ROBOT_PASSWORD}
      clientId: ${EDUCATES_EXAMPLE_ROBOT_CLIENT_ID}
      clientSecret: ${EDUCATES_EXAMPLE_ROBOT_CLIENT_SECRET}
```

--------------------------------

### Check Backend Health with Curl

Source: https://terasky-oss.github.io/backstage-plugins/plugins/kubernetes/backend/install

Tests the health of the Kubernetes Resources backend plugin by sending a GET request to the health endpoint using curl.

```bash
curl http://localhost:7007/api/kubernetes-resources/health
```

--------------------------------

### Spring Initializer Template Examples

Source: https://terasky-oss.github.io/backstage-plugins/plugins/spring-initializer/backend/configure

Provides examples of minimal and complete template implementations for generating Spring Boot projects within a Backstage software template.

```yaml
steps:
  - id: generate-spring
    name: Generate Spring Boot Project
    action: terasky:spring-initializer
    input:
      dependencies: 'web'
```

```yaml
steps:
  - id: fetch-base
    name: Fetch Base
    action: fetch:template
    input:
      url: ./skeleton
      values:
        name: ${{ parameters.name }}

  - id: generate-spring
    name: Generate Spring Boot Project
    action: terasky:spring-initializer
    input:
      type: ${{ parameters.projectType }}
      language: ${{ parameters.language }}
      bootVersion: ${{ parameters.bootVersion }}
      groupId: ${{ parameters.groupId }}
      artifactId: ${{ parameters.artifactId }}
      name: ${{ parameters.name }}
      description: ${{ parameters.description }}
      packageName: ${{ parameters.packageName }}
      packaging: ${{ parameters.packaging }}
      javaVersion: ${{ parameters.javaVersion }}
      dependencies: ${{ parameters.dependencies }}
      outputPath: './spring-app'

  - id: publish
    name: Publish to Repository
    action: publish:github
    input:
      description: ${{ parameters.description }}
      repoUrl: ${{ parameters.repoUrl }}
      defaultBranch: main
      sourcePath: './spring-app'
```

--------------------------------

### Backstage Configuration for VCF Operations Instances (YAML)

Source: https://terasky-oss.github.io/backstage-plugins/plugins/vcf/operations/overview

Configuration example for setting up VCF Operations instances in Backstage's app-config.yaml. This includes details like base URL, major version, and authentication credentials.

```yaml
vcfOperations:
  instances:
    - name: vcf-ops-prod
      baseUrl: 'https://vcf-ops.company.local'
      majorVersion: 9  # VCF 9 with any-apps tenants
      relatedVCFAInstances:
        - vcfa-instance-name
      authentication:
        username: 'admin'
        password: 'VMware123!VMware123!'
    - name: vcf-ops-dev
      baseUrl: 'https://vcf-ops-dev.company.local'
      majorVersion: 9  # VCF 9 with any-apps tenants
      authentication:
        username: 'monitoring'
        password: 'SecurePassword123!'
```

--------------------------------

### Register CRD Module in Backstage App

Source: https://terasky-oss.github.io/backstage-plugins/plugins/api-docs-module-crd/frontend/install

Integrates the CRD module into the Backstage application by importing and adding it to the features array in the new frontend system.

```typescript
import { createApp } from '@backstage/app-defaults';

// Add this import
import apiDocsModuleCrd from '@terasky/backstage-plugin-api-docs-module-crd';

const app = createApp({
  features: [
    // ... other features
    apiDocsModuleCrd, // Add this line
  ],
});
```

--------------------------------

### VCFA VKS Instance Name Prefixing

Source: https://terasky-oss.github.io/backstage-plugins/plugins/vcf/automation/vks-cluster-provider/configure

Configuration example showing how to use the optional name field to prefix discovered cluster names, preventing collisions in multi-environment setups.

```yaml
vcfaVks:
  instances:
    - baseUrl: https://vcfa.example.com
      name: prod
      orgName: vcfa
      authentication:
        username: ${VCFA_USERNAME}
        password: ${VCFA_PASSWORD}
```

--------------------------------

### List All Conditional Policies

Source: https://terasky-oss.github.io/backstage-plugins/plugins/rbac-mcp/backend/usage

Retrieves a list of all defined conditional permission policies within the system. This action can be used to get a global overview of all custom access control rules.

```json
{
  "action": "list_conditional_policies"
}
```

--------------------------------

### Integrate via New Frontend System

Source: https://terasky-oss.github.io/backstage-plugins/plugins/crossplane/frontend/install

Demonstrates how to register the plugin using the new Backstage frontend system (alpha), which automates route configuration.

```typescript
import { createApp } from '@backstage/frontend-defaults';
import { crossplaneResourcesPlugin } from '@terasky/backstage-plugin-crossplane-resources-frontend/alpha';

export default createApp({
  features: [
    crossplaneResourcesPlugin,
  ],
});
```

--------------------------------

### Get Role Details

Source: https://terasky-oss.github.io/backstage-plugins/plugins/rbac-mcp/backend/usage

Retrieves comprehensive information about a specific role, including its members, description, and associated permissions (both direct and conditional). This is useful for understanding role assignments and access policies.

```json
{
  "action": "get_role_details",
  "input": {
    "roleRef": "role:default/developers"
  }
}
```

--------------------------------

### Configure Backend Authentication Providers

Source: https://terasky-oss.github.io/backstage-plugins/plugins/signin-page/frontend/install

Sets up the necessary OAuth credentials in the backend configuration to support the authentication providers enabled in the frontend.

```yaml
auth:
  environment: development
  providers:
    github:
      development:
        clientId: ${GITHUB_CLIENT_ID}
        clientSecret: ${GITHUB_CLIENT_SECRET}
```

--------------------------------

### Get User Effective Permissions

Source: https://terasky-oss.github.io/backstage-plugins/plugins/rbac-mcp/backend/usage

Audits and displays all permissions assigned to a given user or group, including those inherited through roles. The response details the user/group, their assigned roles, and the specific permissions granted, along with their sources.

```json
{
  "action": "get_user_effective_permissions",
  "input": {
    "memberRef": "user:default/john.doe"
  }
}
```

--------------------------------

### Verify Plugin Installation (grep)

Source: https://terasky-oss.github.io/backstage-plugins/plugins/spectrocloud/auth/frontend/install

Verifies that the SpectroCloud authentication plugin has been successfully added to the Backstage application's dependencies by searching the package.json file.

```bash
grep "@terasky/backstage-plugin-spectrocloud-auth" packages/app/package.json
```

--------------------------------

### Configure Kubernetes RBAC for Backstage Ingestor (YAML)

Source: https://terasky-oss.github.io/backstage-plugins/plugins/kubernetes-ingestor/backend/install

Defines the necessary ClusterRole and ClusterRoleBinding in Kubernetes to grant the Backstage Kubernetes Ingestor plugin the required permissions for accessing cluster resources. This ensures the plugin can list, get, and watch resources.

```yaml
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: backstage-kubernetes-ingestor
rules:
  - apiGroups: ["*"]
    resources: ["*"]
    verbs: ["get", "list", "watch"]
---
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
  name: backstage-kubernetes-ingestor
subjects:
  - kind: ServiceAccount
    name: backstage-kubernetes-ingestor
    namespace: backstage
roleRef:
  kind: ClusterRole
  name: backstage-kubernetes-ingestor
  apiGroup: rbac.authorization.k8s.io

```

--------------------------------

### Dependency Parameter Formatting

Source: https://terasky-oss.github.io/backstage-plugins/plugins/spring-initializer/backend/about

Shows the expected format for passing project dependencies to the API as a comma-separated string.

```javascript
const dependencies = 'web,data-jpa,security,actuator';
params.append('dependencies', dependencies);
```

--------------------------------

### Register VCF Operations Backend Plugin (TypeScript)

Source: https://terasky-oss.github.io/backstage-plugins/plugins/vcf/operations/backend/install

Registers the VCF Operations backend plugin within your Backstage application's backend code. This involves importing the plugin and adding it to the backend instance before starting the server. Requires '@backstage/backend-defaults'.

```typescript
import { createBackend } from '@backstage/backend-defaults';

const backend = createBackend();

// ... other plugin registrations

// Add VCF Operations backend plugin
backend.add(import('@terasky/backstage-plugin-vcf-operations-backend'));

backend.start();

```

--------------------------------

### Integrate AI Rules Components into Backstage Entity Pages (TypeScript)

Source: https://terasky-oss.github.io/backstage-plugins/plugins/ai-rules-plugin/frontend/install

Demonstrates how to add AI Rules components to entity pages in Backstage by importing and utilizing them within the `EntityPage.tsx` file. It shows both a unified component for all tabs and individual components, along with an example of a custom title.

```typescript
import {
  AiInstructionsComponent,
  AIRulesComponent,
  MCPServersComponent,
  IgnoreFilesComponent,
  AgentConfigsComponent,
  AgentSkillsComponent,
} from '@terasky/backstage-plugin-ai-rules';

const componentPage = (
  <EntityLayout>
    {/* ... other tabs */}

    {/* Option 1: Unified Component with all 5 tabs (Recommended) */}
    <EntityLayout.Route path="/ai-rules" title="AI Rules">
      <AiInstructionsComponent />
    </EntityLayout.Route>

    {/* Option 2: Individual standalone components */}
    <EntityLayout.Route path="/ai-rules" title="AI Rules">
      <AIRulesComponent />
    </EntityLayout.Route>
    <EntityLayout.Route path="/mcp-servers" title="MCP Servers">
      <MCPServersComponent />
    </EntityLayout.Route>
    <EntityLayout.Route path="/ignore-files" title="Ignore Files">
      <IgnoreFilesComponent />
    </EntityLayout.Route>
    <EntityLayout.Route path="/agent-configs" title="Agent Configs">
      <AgentConfigsComponent />
    </EntityLayout.Route>
    <EntityLayout.Route path="/agent-skills" title="Agent Skills">
      <AgentSkillsComponent />
    </EntityLayout.Route>

    {/* With custom title */}
    <EntityLayout.Route path="/coding-rules" title="Coding Rules">
      <AiInstructionsComponent title="Development Guidelines" />
    </EntityLayout.Route>
  </EntityLayout>
);
```

--------------------------------

### Install Spring Initializer Plugin

Source: https://terasky-oss.github.io/backstage-plugins/plugins/spring-initializer/frontend/install

Command to add the Spring Initializer plugin package to your Backstage application using yarn.

```bash
yarn --cwd packages/app add @terasky/backstage-plugin-spring-initializer
```

--------------------------------

### Integrate AI Rules Plugin with New Backstage Frontend System (TypeScript)

Source: https://terasky-oss.github.io/backstage-plugins/plugins/ai-rules-plugin/frontend/install

Shows how to integrate the AI Coding Rules plugin using the new Backstage frontend system (alpha). This approach simplifies setup by automatically integrating all five tabs without manual route configuration in `EntityPage.tsx`.

```typescript
import { createApp } from '@backstage/frontend-defaults';
import { aiRulesPlugin } from '@terasky/backstage-plugin-ai-rules/alpha';

export default createApp({
  features: [
    aiRulesPlugin,
    // ...
  ],
});
```

--------------------------------

### Verification

Source: https://terasky-oss.github.io/backstage-plugins/plugins/ai-rules-plugin/backend/install

How to verify the successful installation and functionality of the plugin.

```APIDOC
## Verification

### 1. Check Backend Logs

Start your backend and check for successful plugin registration:

```bash
yarn dev
```

Look for log entries:

```
[ai-rules-backend] Plugin loaded successfully
[ai-rules-backend] API routes registered at /api/ai-rules
```

### 2. Test API Endpoints

Test all five endpoints directly:

```bash
BASE="http://localhost:7007/api/ai-rules"
ENTITY="component:default/my-service"

# AI Rules
curl "$BASE/rules?entityRef=$ENTITY"

# MCP Servers
curl "$BASE/mcp-servers?entityRef=$ENTITY"

# Ignore Files
curl "$BASE/ignore-files?entityRef=$ENTITY"

# Agent Configs
curl "$BASE/agent-configs?entityRef=$ENTITY"

# Agent Skills
curl "$BASE/skills?entityRef=$ENTITY"
```

Expected response format (empty repository):

```json
{
  "rules": [],
  "totalCount": 0,
  "ruleTypes": []
}
```

### 3. Check Entity Resolution

Verify that entities with source locations are properly resolved:

```bash
curl "http://localhost:7007/api/ai-rules/rules?entityRef=component:default/my-service&ruleTypes=cursor,copilot,windsurf"
```
```

--------------------------------

### Check Plugin Installation Status (Yarn)

Source: https://terasky-oss.github.io/backstage-plugins/plugins/ai-rules-plugin/backend/install

Verifies if the AI Coding Rules backend plugin package is installed in your Backstage project's backend. This command is useful for troubleshooting installation issues.

```bash
yarn --cwd packages/backend list --pattern @terasky/backstage-plugin-ai-rules-backend

```

--------------------------------

### Initial State Builder Example (TypeScript)

Source: https://terasky-oss.github.io/backstage-plugins/plugins/entity-scaffolder/frontend/configure

Demonstrates how to build the initial state for the scaffolder form by mapping entity data to template fields. This includes basic metadata, annotations, and custom transformations.

```typescript
const buildInitialState = (entity: Entity) => ({
  // Basic metadata mapping
  name: entity.metadata.name,
  namespace: entity.metadata.namespace,

  // Extract from annotations
  cluster: entity.metadata?.annotations?.['backstage.io/managed-location']?.split(": ")[1],

  // Custom transformations
  labels: Object.entries(entity.metadata.labels || {}).map(
    ([key, value]) => `${key}=${value}`
  ),
});
```

--------------------------------

### Add Required Packages to Backstage Backend

Source: https://terasky-oss.github.io/backstage-plugins/plugins/spectrocloud/backend/install

Installs the SpectroCloud backend and common packages into the Backstage backend using yarn. This is a prerequisite for integrating the plugin.

```bash
yarn --cwd packages/backend add @terasky/backstage-plugin-spectrocloud-backend @terasky/backstage-plugin-spectrocloud-common
```

--------------------------------

### Configure Environment Variables

Source: https://terasky-oss.github.io/backstage-plugins/plugins/vcf/sso/backend/install

Sets the required OIDC client credentials as environment variables for secure access by the backend.

```bash
export VCFSSO_CLIENT_ID="your-client-id"
export VCFSSO_CLIENT_SECRET="your-client-secret"
```