Configure and manage connections

Connections are configured as an array at the root of app-config.yaml. The default service loads the array at backend startup, validates every entry, and assigns display titles where they are omitted.

Experimental configuration

The connections configuration format is experimental and can change while the connections framework is developed.

Configure a connection

The following connection gives backend plugins and modules token-authenticated access to GitHub:

app-config.yaml

connections:
  - type: github
    title: GitHub production
    host: github.com
    auth:
      - method: token
        token: ${GITHUB_TOKEN}

Set type to one of the built-in connection types. The connection type determines the allowed connection fields, authentication methods, lookup query, and validation rules.

Store secret values outside source control and reference them through environment variable substitution. The connection service validates the resolved values, so a missing or invalid secret causes startup to fail with configuration context.

Configure unauthenticated access

Every connection requires at least one authentication entry. When a type supports unauthenticated access, use the none method:

app-config.yaml

connections:
  - type: gitlab
    host: gitlab.com
    auth:
      - method: none

Not every type supports none. For example, harness requires token authentication and aws-codecommit requires either access-key or assume-role authentication.

Configure multiple endpoints of one type

Connection types that use the host lookup strategy allow multiple entries when each entry has a different host:

app-config.yaml

connections:
  - type: github
    title: Public GitHub
    host: github.com
    auth:
      - method: token
        token: ${GITHUB_TOKEN}

  - type: github
    title: Company GitHub
    host: github.example.com
    apiBaseUrl: https://github.example.com/api/v3
    rawBaseUrl: https://github.example.com/raw
    auth:
      - method: token
        token: ${GITHUB_ENTERPRISE_TOKEN}

For host-based types, ConnectionsService.find parses the consumer's URL and matches its host exactly. Do not include a scheme or path in host.

The default connection title is the connection type's title. When more than one connection has the same type, the default includes the host, such as GitHub (github.example.com). Set title when an environment-specific name is clearer.

Duplicate multiton connections with the same type and host are rejected. Singleton types, such as aws, reject a second entry of the same type.

Configure multiple authentication entries

A connection can contain more than one authentication entry. This supports plugin-specific credentials and type-specific selection such as choosing a GitHub App for one organization.

Select a credential for a plugin

Use plugin scoping through match.plugins on an authentication entry to make it visible only to the listed plugin IDs:

app-config.yaml

connections:
  - type: github
    host: github.com
    auth:
      - method: token
        title: Catalog token
        token: ${GITHUB_CATALOG_TOKEN}
        match:
          plugins:
            - catalog
      - method: token
        title: Default token
        token: ${GITHUB_DEFAULT_TOKEN}

For the catalog plugin, explicitly matched entries are placed before unrestricted entries. Other plugins cannot see GITHUB_CATALOG_TOKEN and use the unrestricted entry.

You can also restrict the complete connection:

app-config.yaml

connections:
  - type: harness
    host: app.harness.io
    match:
      plugins:
        - harness
    auth:
      - method: token
        token: ${HARNESS_TOKEN}

Other plugins do not see this connection, even if they declare the harness type.

note

Plugin matching controls which static credentials are handed to a backend plugin. It does not grant external permissions or authorize frontend users.

Select a GitHub App by organization

The GitHub type uses the first path segment of the query URL as the organization. It prefers an app whose orgs list contains that organization:

app-config.yaml

connections:
  - type: github
    host: github.com
    auth:
      - method: app
        title: Backstage organization app
        appId: ${GITHUB_BACKSTAGE_APP_ID}
        privateKey: ${GITHUB_BACKSTAGE_PRIVATE_KEY}
        clientId: ${GITHUB_BACKSTAGE_CLIENT_ID}
        clientSecret: ${GITHUB_BACKSTAGE_CLIENT_SECRET}
        orgs:
          - backstage
      - method: token
        token: ${GITHUB_FALLBACK_TOKEN}

Use lowercase organization names in orgs because the URL organization is normalized to lowercase before matching.

GitHub authentication selection prefers, in order:

1. An app whose orgs contains the query organization.
2. An app with no orgs restriction.
3. The only configured app, when exactly one app remains.
4. A token.
5. The none method.

The selected method must also appear in the consumer's authMethods list.

Configure AWS accounts

The aws type is different from host-based types. One singleton connection contains an account authentication entry for each AWS account:

app-config.yaml

connections:
  - type: aws
    roleName: BackstageReadRole
    region: eu-west-1
    auth:
      - method: account
        title: Main AWS account
        mainAccount: true
        profile: backstage-main
      - method: account
        title: Workload account
        accountId: '123456789012'
        roleName: BackstageReadRole

A lookup can provide an accountId or an Amazon Resource Name (ARN). AWS uses an exact account entry when one exists, then falls back to the entry marked mainAccount. A connection-level roleName requires a main-account entry, because that entry supplies the credentials used to assume the role in accounts without their own entry.

See the AWS connection type guide for the available fields and validation constraints.

Change a connection

Connection configuration is static. To change a host, endpoint, credential, plugin match, or authentication method:

1. Update the relevant entry in the configuration source for the environment.
2. Update any secret referenced by the entry.
3. Restart the backend so the default service reloads and validates the full connection list.
4. Exercise a plugin lookup for the affected type and target.

Changing an authentication method can affect consumers. Each consumer lists the methods it understands, and a lookup fails if the configured selection resolves to an unsupported method. Check the consuming plugins before removing an authentication entry or changing its priority.

Backstage configuration arrays are replaced as a whole when configuration sources are merged. If more than one configuration file defines connections, the higher-priority array replaces the lower-priority array. Include the full environment-specific connection list in the overriding source, or use config includes and environment variable substitution to keep values organized.

Migrate from legacy integrations

At backend startup, the default connection service automatically reads both explicit connections configuration and supported legacy integrations configuration. It converts the legacy integrations, including the legacy top-level aws configuration, into in-memory connections before making them available to plugins. Adopters do not need to enable this conversion or change their existing integrations while plugins migrate to the connection service.

The conversion does not rewrite app-config.yaml. It only determines which connections the running backend loads.

Migrate one type at a time

Legacy and explicit entries can be used together when they have different connection types. Given this configuration:

app-config.yaml

# Legacy configuration
integrations:
  github:
    - host: github.com
      token: ${GITHUB_TOKEN}

# Explicit connection configuration
connections:
  - type: gitlab
    host: gitlab.com
    auth:
      - method: token
        token: ${GITLAB_TOKEN}

The service automatically converts and loads the legacy GitHub integration alongside the explicit GitLab connection.

Explicit connections replace the legacy type

The precedence rule applies to the complete connection type, not to individual hosts. If at least one explicit connection exists for a type, the service drops all converted legacy integration entries of that type from its runtime connection list.

For example:

app-config.yaml

integrations:
  github:
    - host: github.com
      token: ${GITHUB_TOKEN}
    - host: github.example.com
      token: ${GITHUB_ENTERPRISE_TOKEN}

connections:
  - type: github
    host: github.example.com
    auth:
      - method: token
        token: ${GITHUB_ENTERPRISE_CONNECTION_TOKEN}

The running backend loads only the explicit github connection. Both converted legacy GitHub entries are dropped, including the github.com entry whose host does not overlap. The service logs one warning for the overlapping github type.

In summary:

• With no explicit connection for a type, all supported legacy entries of that type are converted and loaded automatically.
• With any explicit connection for a type, all converted legacy entries of that type are dropped.
• Legacy and explicit entries of different types are loaded together.

The same rule applies to the converted legacy top-level aws configuration.

Diagnose configuration and lookup failures

The service reports invalid configuration during backend startup. Common causes include:

• An unknown connection type or authentication method.
• A missing required field.
• An empty or missing auth array.
• Two connections with the same type and host.
• More than one singleton connection.
• A whole-connection validation failure, such as duplicate AWS account IDs.

At lookup time, distinguish these outcomes:

• NotFoundError means no configured connection matched the type and query, or the type-specific authentication selector found no candidate.
• NotAllowedError means the plugin cannot see an authentication entry or the selected method is not supported by the consumer.
• InputError can indicate an invalid query, such as a malformed URL, or a lookup for a connection type the plugin did not declare.

See Consume connections for error handling in plugin code.