@spacelift-io/backstage-integration-backend/README.md

Backstage plugin for integrating Spacelift.io with Backstage

# Spacelift Backend Plugin

This backend plugin for Backstage integrates with Spacelift to provide information about your Spacelift stacks and runs.

## Installation

1. Install the plugin package in your Backstage backend:

   ```bash
   # From your Backstage root directory
   yarn --cwd packages/backend add @spacelift-io/backstage-integration-backend
   ```

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

   ```ts
   // packages/backend/src/index.ts
   import { createBackend } from '@backstage/backend-defaults';

   const backend = createBackend();
   // ...
   backend.add(import('@spacelift-io/backstage-integration-backend'));
   // ...
   await backend.start();
   ```

## Configuration

To use this plugin, you need to configure it in your `app-config.yaml`. Add the following section:

```yaml
spacelift:
  hostUrl: '<your-subdomain>.app.spacelift.io' # Your Spacelift instance URL (WITHOUT https://)
  apiKey: ${SPACELIFT_API_KEY} # Your Spacelift API Key ID
  apiSecret: ${SPACELIFT_API_SECRET} # Your Spacelift API Key Secret
  readOnly: false # Optional: Set to true to disable trigger functionality (default: false)
```

Make sure to replace `<your-subdomain>` with your actual Spacelift subdomain.
The `apiKey` and `apiSecret` should be stored securely, for example, as environment variables.

### Read-Only Mode

You can enable read-only mode by setting `readOnly: true` in your configuration. When enabled:

- The trigger run functionality will be disabled
- Users will not be able to trigger runs from the frontend
- The backend will return a `403 Forbidden` error if someone attempts to trigger a run via the API
- All other read operations (viewing stacks, etc.) will continue to work normally

This is useful for environments where you want to provide visibility into Spacelift stacks without allowing users to trigger runs.

> **Tip:** For additional security, admins can also create a Spacelift API key with read-only permissions. This ensures write operations are disabled at the API key level, providing defense-in-depth even if the `readOnly` configuration is accidentally omitted.

## Compatibility

This plugin requires:

- `@backstage/backend-plugin-api` >= 1.3.0
- `@backstage/backend-defaults` >= 0.9.0
- `@backstage/catalog-client` >= 1.9.1

It is compatible with Backstage 1.17.0 or later.

## Frontend Plugin

This backend plugin is intended to be used with the [Spacelift Frontend Plugin](https://github.com/spacelift-io/backstage-plugins/blob/main/packages/spacelift-io-frontend/README.md).

## Spacelift Documentation

For more information about Spacelift and its API, please refer to the [official Spacelift documentation](https://docs.spacelift.io/integrations/external-integrations/backstage).