DOCSEARCHbyAlgolia
Submit Docs

SuperPlane Documentation

repository·main·Indexed 26 days ago

https://github.com/superplanehq/superplane

An open source orchestration and automation platform for AI-driven engineering. SuperPlane integrates with AI/LLMs, CI/CD, cloud infrastructure (AWS, Azure, GCP), and observability stacks to automate complex workflows using durable execution, human-in-the-loop approvals, and operational UIs.

Tokens
285.6K
Snippets
570
Records
1.1K
Agent score
90%

What's inside SuperPlane

  1. Overview of SuperPlane

    main

    SuperPlane is an open source automation engine designed for AI-driven engineering. It orchestrates engineering workflows across various tools (Git, LLMs, CI/CD, observability, etc.) using durable execution, human-in-the-loop approvals, and operational UIs.

    Key concepts include:

    • Apps: Deployable units consisting of a workflow graph, custom console UI, and app-scoped memory, versioned in git via canvas.yaml and console.yaml.
    • Canvases: A graph of steps and dependencies that can express multiple workflows.
    • Components: Nodes in a canvas that act as triggers or actions (e.g., deploying a service, opening an incident, or requiring approval).
    • Memory: App-scoped JSON storage that persists across runs.
    • Durable Execution: Runs and payloads are tracked across restarts, allowing failed steps to resume without custom retry logic.

  2. Overview of Service Accounts

    main
    Service accounts are non-human identities used for programmatic access to the SuperPlane API. They are designed for CI/CD pipelines, automation scripts, and machine-to-machine communication. Unlike personal user API tokens, service accounts are independent of individual user lifecycles, preventing automation breakage when users leave an organization, and allow for better audit trails and granular permissions via the existing RBAC system.

  4. Service Account RBAC and Restrictions

    main

    Service accounts are first-class principals in the SuperPlane RBAC system:

    • Role Assignment: Organization admins can assign roles (e.g., org_viewer, org_admin, or custom roles) to service accounts.
    • Group Membership: Service accounts can be added to groups to inherit group-level roles.
    • Restriction: Service accounts cannot be assigned the org_owner role. This role is reserved exclusively for human users.

  5. Manage SuperPlane security and access control

    main

    SuperPlane provides several security mechanisms:

    • RBAC (Role-Based Access Control): Manages user permissions.
    • API Keys: Used for programmatic access via service accounts.
    • Secrets: All secrets are stored in an encrypted format.

  6. Supported Integrations in SuperPlane

    main

    SuperPlane integrates with various third-party tools to provide triggers (events that start workflows) and components (actions that can be executed within workflows). Integrations are categorized by functional domains:

    • AI & LLM: Claude, Cursor, OpenAI, Perplexity.
    • Version Control & CI/CD: Bitbucket, CircleCI, GitHub, GitLab, Harness, Octopus Deploy, Render, Semaphore.
    • Cloud & Infrastructure: AWS (ECR, Lambda, CodeArtifact, CloudWatch, SNS), GCP (Cloud Build, Cloud Functions, Compute), Cloudflare, DigitalOcean, DockerHub, Hetzner Cloud, Azure, OCI, Coolify.
    • Observability: DataDog, Dash0, Grafana, Honeycomb, Logfire, New Relic, Prometheus, Elastic, Sentry.
    • Incident Management: FireHydrant, Incident.io, PagerDuty, Rootly, Statuspage.
    • Communication: Discord, SendGrid, Slack, SMTP, Microsoft Teams, Telegram.
    • Ticketing: Jira, ServiceNow.
    • Developer Tools: Cloudsmith, Daytona, JFrog Artifactory, LaunchDarkly.

    For a complete list of components and specific provider details, refer to the official SuperPlane documentation.

  7. Understand the GCP Event Trigger Architecture

    main

    SuperPlane uses a Cloud Logging Sink + Pub/Sub architecture to react to GCP events in real time. This approach is preferred over Eventarc for its wider regional support and lower provisioning complexity.

    Event Flow

    1. GCP Audit Log: A resource change generates an Admin Activity audit log.
    2. Cloud Logging Sink: A per-trigger sink filters the log (e.g., matching a specific service and method).
    3. Pub/Sub Topic: The sink forwards matching logs to a shared topic: sp-events-{integrationID}.
    4. Push Subscription: A subscription (sp-sub-{integrationID}) delivers the message via HTTP POST to SuperPlane's event endpoint.
    5. SuperPlane Processing: HandleRequest verifies the token, decodes the log, and subscriptionApplies() routes it to the correct trigger via OnIntegrationMessage.

  8. Set up DigitalOcean Integration

    main

    To use DigitalOcean components in SuperPlane, you must provide authentication credentials.

    1. Personal Access Token: Generate a token in the DigitalOcean dashboard.
      • Recommended Name: SuperPlane Integration
      • Expiration: No expiry (or preferred)
      • Scopes: Full Access (or customized)
    2. Access Key (Optional): Required only for Spaces Object Storage components. Create an Access Key ID & Secret Access Key pair in DigitalOcean Spaces with either Full Access or Limited Access to specific buckets.

  9. Connect Prometheus and Alertmanager to SuperPlane

    main

    To use Prometheus and Alertmanager integrations, configure the following connection settings:

    • Prometheus Base URL: The URL of your Prometheus server (e.g., https://prometheus.example.com).
    • Alertmanager Base URL (optional): The URL of your Alertmanager instance. This is required for using Silence components. If omitted, the Prometheus Base URL is used.
    • API Auth: Choose between none, basic, or bearer for API requests.
    • Webhook Secret (recommended): If configured, Alertmanager must include Authorization: Bearer <token> in its webhook requests.

    Manual Alertmanager Setup:

    1. Copy the generated webhook URL from the SuperPlane trigger setup panel.
    2. Add this URL to your Alertmanager configuration (e.g., in alertmanager.yml).
    3. Reload Alertmanager (e.g., via POST /-/reload) to apply changes.

  10. Configure Table Panels in SuperPlane

    main

    Table panels are highly configurable widgets used to display canvas memory, executions, or runs. For ephemeral environment consoles, using a memory data source is the recommended pattern. Tables support custom columns, filtering, sorting, and row-level actions.

    Key configuration components include:

    • dataSource: Defines the data origin (e.g., memory, executions, or runs).
    • columns: Defines the visual representation of data fields.
    • where: An AND list of structured filters to narrow down rows.
    • rowActions: Interactive buttons that trigger canvas nodes.
    type: table
content:
  dataSource:
    kind: memory
    namespace: environments
  render:
    kind: table
    columns:
      - field: pr_number
        label: PR
      - field: status
        label: Health
        format: status
      - field: created_at
        label: Uptime
        format: relative
    where:
      - field: status
        op: neq
        value: destroyed
    rowActions:
      - kind: trigger
        label: Destroy
        node: start
        template: destroy
        variant: danger
        confirm: "Destroy PR #{{ pr_number }}?"
        show: 'status == "running"'
        payload:
          issue.number: "{{ pr_number }}"

  11. Improve AI Assistant accuracy with SKILL.md files

    main

    SuperPlane's AI chat assistant uses component-specific SKILL.md files to ground its reasoning, suggestions, and canvas operations. By providing a SKILL.md file within your component or integration assets, you ensure the AI assistant follows documented best practices, handles required configuration fields correctly, and respects component-specific constraints.

    How it works:

    1. Discovery: The assistant identifies relevant components based on user prompts.
    2. Retrieval: The assistant looks for a SKILL.md file in the component's known location.
    3. Parsing: The assistant extracts actionable guidance such as:
      • Required configuration fields and default values.
      • Input/output expectations and channel mapping notes.
      • Constraints, caveats, and recommended patterns.
    4. Grounding: The assistant prioritizes this guidance over generic assumptions when generating responses or proposed canvas operations.

    Best Practices for Integration Authors:

    • Update regularly: Updates to SKILL.md directly improve the AI's ability to assist users with your component.
    • Be explicit: Include required fields and common pitfalls to reduce the need for manual user corrections.
    • Maintain consistency: Ensure the guidance in SKILL.md aligns with the actual component implementation to prevent the AI from proposing invalid configurations.

  12. Setup Hetzner Cloud Integration

    main

    To use Hetzner Cloud components, you must configure an API Token and, optionally, S3 credentials for Object Storage.

    1. API Token: Create a token in the Hetzner Cloud Console under Project → Security → API Tokens. Ensure it has the Read & Write scope.
    2. Object Storage (Optional): To use S3-compatible components, go to Object Storage in the Hetzner Cloud Console and create S3 credentials (Access Key + Secret Key). Set the region to match your bucket location (e.g., fsn1 or nbg1).