@backstage/integration/dist/index.d.ts

Helpers for managing integrations towards external systems

import { Config } from '@backstage/config';
import { TokenCredential } from '@azure/identity';
import { StorageSharedKeyCredential, AnonymousCredential } from '@azure/storage-blob';
import { ConsumedResponse } from '@backstage/errors';
import { RestEndpointMethodTypes } from '@octokit/rest';

/**
 * Encapsulates a single SCM integration.
 *
 * @public
 */
interface ScmIntegration {
    /**
     * The type of integration, e.g. "github".
     */
    type: string;
    /**
     * A human readable title for the integration, that can be shown to users to
     * differentiate between different integrations.
     */
    title: string;
    /**
     * Resolves an absolute or relative URL in relation to a base URL.
     *
     * This method is adapted for use within SCM systems, so relative URLs are
     * within the context of the root of the hierarchy pointed to by the base
     * URL.
     *
     * For example, if the base URL is  `<repo root url>/folder/a.yaml`, i.e.
     * within the file tree of a certain repo, an absolute path of `/b.yaml` does
     * not resolve to `https://hostname/b.yaml` but rather to
     * `<repo root url>/b.yaml` inside the file tree of that same repo.
     */
    resolveUrl(options: {
        /**
         * The (absolute or relative) URL or path to resolve
         */
        url: string;
        /**
         * The base URL onto which this resolution happens
         */
        base: string;
        /**
         * The line number in the target file to link to, starting with 1. Only applicable when linking to files.
         */
        lineNumber?: number;
    }): string;
    /**
     * Resolves the edit URL for a file within the SCM system.
     *
     * Most SCM systems have a web interface that allows viewing and editing files
     * in the repository. The returned URL directly jumps into the edit mode for
     * the file.
     * If this is not possible, the integration can fall back to a URL to view
     * the file in the web interface.
     *
     * @param url - The absolute URL to the file that should be edited.
     */
    resolveEditUrl(url: string): string;
}
/**
 * Encapsulates several integrations, that are all of the same type.
 *
 * @public
 */
interface ScmIntegrationsGroup<T extends ScmIntegration> {
    /**
     * Lists all registered integrations of this type.
     */
    list(): T[];
    /**
     * Fetches an integration of this type by URL.
     *
     * @param url - A URL that matches a registered integration of this type
     */
    byUrl(url: string | URL): T | undefined;
    /**
     * Fetches an integration of this type by host name.
     *
     * @param host - A host name that matches a registered integration of this type
     */
    byHost(host: string): T | undefined;
}
/**
 * A factory function that creates an integration group based on configuration.
 *
 * @public
 */
type ScmIntegrationsFactory<T extends ScmIntegration> = (options: {
    config: Config;
}) => ScmIntegrationsGroup<T>;
/**
 * Encapsulates information about the RateLimit state
 *
 * @public
 */
interface RateLimitInfo {
    isRateLimited: boolean;
}

/**
 * The configuration parameters for a single AWS S3 provider.
 *
 * @public
 */
type AwsS3IntegrationConfig = {
    /**
     * Host, derived from endpoint, and defaults to amazonaws.com
     */
    host: string;
    /**
     * (Optional) AWS Endpoint.
     * The endpoint URI to send requests to. The default endpoint is built from the configured region.
     * @see https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/S3.html#constructor-property
     *
     * Supports non-AWS providers, e.g. for LocalStack, endpoint may look like http://localhost:4566
     */
    endpoint?: string;
    /**
     * (Optional) Whether to use path style URLs when communicating with S3.
     * Defaults to false.
     * This allows providers like LocalStack, Minio and Wasabi (and possibly others) to be used.
     */
    s3ForcePathStyle?: boolean;
    /**
     * (Optional) User access key id
     */
    accessKeyId?: string;
    /**
     * (Optional) User secret access key
     */
    secretAccessKey?: string;
    /**
     * (Optional) ARN of role to be assumed
     */
    roleArn?: string;
    /**
     * (Optional) External ID to use when assuming role
     */
    externalId?: string;
};
/**
 * Reads a single Aws S3 integration config.
 *
 * @param config - The config object of a single integration
 * @public
 */
declare function readAwsS3IntegrationConfig(config: Config): AwsS3IntegrationConfig;
/**
 * Reads a set of AWS S3 integration configs, and inserts some defaults for
 * public Amazon AWS if not specified.
 *
 * @param configs - The config objects of the integrations
 * @public
 */
declare function readAwsS3IntegrationConfigs(configs: Config[]): AwsS3IntegrationConfig[];

/**
 * Integrates with AWS S3 or compatible solutions.
 *
 * @public
 */
declare class AwsS3Integration implements ScmIntegration {
    private readonly integrationConfig;
    static factory: ScmIntegrationsFactory<AwsS3Integration>;
    get type(): string;
    get title(): string;
    get config(): AwsS3IntegrationConfig;
    constructor(integrationConfig: AwsS3IntegrationConfig);
    resolveUrl(options: {
        url: string;
        base: string;
        lineNumber?: number | undefined;
    }): string;
    resolveEditUrl(url: string): string;
}

/**
 * The configuration parameters for a single AWS CodeCommit provider.
 *
 * @public
 */
type AwsCodeCommitIntegrationConfig = {
    /**
     * Host, git host derived from region
     */
    host: string;
    /**
     * (Optional) User access key id
     */
    accessKeyId?: string;
    /**
     * (Optional) User secret access key
     */
    secretAccessKey?: string;
    /**
     * (Optional) ARN of role to be assumed
     */
    roleArn?: string;
    /**
     * (Optional) External ID to use when assuming role
     */
    externalId?: string;
    /**
     * region to use for AWS (default: us-east-1)
     */
    region: string;
};
/**
 * Reads a single Aws CodeCommit integration config.
 *
 * @param config - The config object of a single integration
 * @public
 */
declare function readAwsCodeCommitIntegrationConfig(config: Config): AwsCodeCommitIntegrationConfig;
/**
 * Reads a set of AWS CodeCommit integration configs, and inserts some defaults for
 * public Amazon AWS if not specified.
 *
 * @param configs - The config objects of the integrations
 * @public
 */
declare function readAwsCodeCommitIntegrationConfigs(configs: Config[]): AwsCodeCommitIntegrationConfig[];

/**
 * Integrates with AWS CodeCommit.
 *
 * @public
 */
declare class AwsCodeCommitIntegration implements ScmIntegration {
    private readonly integrationConfig;
    static factory: ScmIntegrationsFactory<AwsCodeCommitIntegration>;
    get type(): string;
    get config(): AwsCodeCommitIntegrationConfig;
    get title(): string;
    constructor(integrationConfig: AwsCodeCommitIntegrationConfig);
    resolveUrl(options: {
        url: string;
        base: string;
        lineNumber?: number | undefined;
    }): string;
    resolveEditUrl(url: string): string;
}

/**
 * The configuration parameters for a single Azure Blob Storage account.
 *
 * @public
 */
type AzureBlobStorageIntegrationConfig = {
    /**
     * The name of the Azure Storage Account, e.g., "mystorageaccount".
     */
    accountName?: string;
    /**
     * The primary or secondary key for the Azure Storage Account.
     * Only required if connectionString or SAS token are not specified.
     */
    accountKey?: string;
    /**
     * A Shared Access Signature (SAS) token for limited access to resources.
     */
    sasToken?: string;
    /**
     * A full connection string for the Azure Storage Account.
     * This includes the account name, key, and endpoint details.
     */
    connectionString?: string;
    /**
     * Optional endpoint suffix for custom domains or sovereign clouds.
     * e.g., "core.windows.net" for public Azure or "core.usgovcloudapi.net" for US Government cloud.
     */
    endpointSuffix?: string;
    /**
     * The host of the target that this matches on, e.g., "blob.core.windows.net".
     */
    host: string;
    endpoint?: string;
    /**
     * Optional credential to use for Azure Active Directory authentication.
     */
    aadCredential?: {
        /**
         * The client ID of the Azure AD application.
         */
        clientId: string;
        /**
         * The tenant ID for Azure AD.
         */
        tenantId: string;
        /**
         * The client secret for the Azure AD application.
         */
        clientSecret: string;
    };
};
/**
 * Reads a single Azure Blob Storage integration config.
 *
 * @param config - The config object of a single integration.
 * @public
 */
declare function readAzureBlobStorageIntegrationConfig(config: Config): AzureBlobStorageIntegrationConfig;
/**
 * Reads a set of Azure Blob Storage integration configs.
 *
 * @param configs - All of the integration config objects.
 * @public
 */
declare function readAzureBlobStorageIntegrationConfigs(configs: Config[]): AzureBlobStorageIntegrationConfig[];

/**
 * Microsoft Azure Blob storage based integration.
 *
 * @public
 */
declare class AzureBlobStorageIntergation implements ScmIntegration {
    private readonly integrationConfig;
    static factory: ScmIntegrationsFactory<AzureBlobStorageIntergation>;
    get type(): string;
    get title(): string;
    get config(): AzureBlobStorageIntegrationConfig;
    constructor(integrationConfig: AzureBlobStorageIntegrationConfig);
    resolveUrl(options: {
        url: string;
        base: string;
        lineNumber?: number | undefined;
    }): string;
    resolveEditUrl(url: string): string;
}

/**
 * This allows implementations to be provided to retrieve Azure Storage accounts credentials.
 *
 * @public
 *
 */
interface AzureCredentialsManager {
    getCredentials(accountName: string): Promise<TokenCredential | StorageSharedKeyCredential | AnonymousCredential>;
}

/**
 * The configuration parameters for a single Azure provider.
 *
 * @public
 */
type AzureIntegrationConfig = {
    /**
     * The host of the target that this matches on, e.g. "dev.azure.com".
     *
     * Currently only "dev.azure.com" is supported.
     */
    host: string;
    /**
     * The authorization token to use for requests.
     *
     * If no token is specified, anonymous access is used.
     *
     * @deprecated Use `credentials` instead.
     */
    token?: string;
    /**
     * The credential to use for requests.
     *
     * If no credential is specified anonymous access is used.
     *
     * @deprecated Use `credentials` instead.
     */
    credential?: AzureDevOpsCredential;
    /**
     * The credentials to use for requests. If multiple credentials are specified the first one that matches the organization is used.
     * If not organization matches the first credential without an organization is used.
     *
     * If no credentials are specified at all, either a default credential (for Azure DevOps) or anonymous access (for Azure DevOps Server) is used.
     */
    credentials?: AzureDevOpsCredential[];
    /**
     * Signing key for commits
     */
    commitSigningKey?: string;
};
/**
 * The kind of Azure DevOps credential.
 * @public
 */
type AzureDevOpsCredentialKind = 'PersonalAccessToken' | 'ClientSecret' | 'ManagedIdentity' | 'ManagedIdentityClientAssertion';
/**
 * Common fields for the Azure DevOps credentials.
 * @public
 */
type AzureCredentialBase = {
    /**
     * The kind of credential.
     */
    kind: AzureDevOpsCredentialKind;
    /**
     * The Azure DevOps organizations for which to use this credential.
     */
    organizations?: string[];
};
/**
 * A client secret credential that was generated for an App Registration.
 * @public
 */
type AzureClientSecretCredential = AzureCredentialBase & {
    kind: 'ClientSecret';
    /**
     * The Entra ID tenant
     */
    tenantId: string;
    /**
     * The client id
     */
    clientId: string;
    /**
     * The client secret
     */
    clientSecret: string;
};
/**
 * A client assertion credential that uses a managed identity to generate a client assertion (JWT).
 * @public
 */
type AzureManagedIdentityClientAssertionCredential = AzureCredentialBase & {
    kind: 'ManagedIdentityClientAssertion';
    /**
     * The Entra ID tenant
     */
    tenantId: string;
    /**
     * The client ID of the app registration you want to authenticate as.
     */
    clientId: string;
    /**
     * The client ID of the managed identity used to generate a client assertion (JWT).
     * Set to "system-assigned" to automatically use the system-assigned managed identity.
     * For user-assigned managed identities, specify the client ID of the managed identity you want to use.
     */
    managedIdentityClientId: 'system-assigned' | string;
};
/**
 * A managed identity credential.
 * @public
 */
type AzureManagedIdentityCredential = AzureCredentialBase & {
    kind: 'ManagedIdentity';
    /**
     * The clientId
     */
    clientId: 'system-assigned' | string;
};
/**
 * A personal access token credential.
 * @public
 */
type PersonalAccessTokenCredential = AzureCredentialBase & {
    kind: 'PersonalAccessToken';
    personalAccessToken: string;
};
/**
 * The general shape of a credential that can be used to authenticate to Azure DevOps.
 * @public
 */
type AzureDevOpsCredentialLike = Omit<Partial<AzureClientSecretCredential> & Partial<AzureManagedIdentityClientAssertionCredential> & Partial<AzureManagedIdentityCredential> & Partial<PersonalAccessTokenCredential>, 'kind'>;
/**
 * Credential used to authenticate to Azure DevOps.
 * @public
 */
type AzureDevOpsCredential = AzureClientSecretCredential | AzureManagedIdentityClientAssertionCredential | AzureManagedIdentityCredential | PersonalAccessTokenCredential;
/**
 * Reads a single Azure integration config.
 *
 * @param config - The config object of a single integration
 * @public
 */
declare function readAzureIntegrationConfig(config: Config): AzureIntegrationConfig;
/**
 * Reads a set of Azure integration configs, and inserts some defaults for
 * public Azure if not specified.
 *
 * @param configs - All of the integration config objects
 * @public
 */
declare function readAzureIntegrationConfigs(configs: Config[]): AzureIntegrationConfig[];

/**
 * Microsoft Azure based integration.
 *
 * @public
 */
declare class AzureIntegration implements ScmIntegration {
    private readonly integrationConfig;
    static factory: ScmIntegrationsFactory<AzureIntegration>;
    constructor(integrationConfig: AzureIntegrationConfig);
    get type(): string;
    get title(): string;
    get config(): AzureIntegrationConfig;
    resolveUrl(options: {
        url: string;
        base: string;
        lineNumber?: number;
    }): string;
    resolveEditUrl(url: string): string;
}

/**
 * The configuration parameters for a single Bitbucket Cloud API provider.
 *
 * @public
 */
type BitbucketCloudIntegrationConfig = {
    /**
     * Constant. bitbucket.org
     */
    host: string;
    /**
     * Constant. https://api.bitbucket.org/2.0
     */
    apiBaseUrl: string;
    /**
     * The username to use for requests to Bitbucket Cloud (bitbucket.org).
     */
    username?: string;
    /**
     * Authentication with Bitbucket Cloud (bitbucket.org) is done using app passwords.
     *
     * See https://support.atlassian.com/bitbucket-cloud/docs/app-passwords/
     */
    appPassword?: string;
    /**
     * The access token to use for requests to Bitbucket Cloud (bitbucket.org).
     */
    token?: string;
    /** PGP private key for signing commits. */
    commitSigningKey?: string;
};
/**
 * Reads a single Bitbucket Cloud integration config.
 *
 * @param config - The config object of a single integration
 * @public
 */
declare function readBitbucketCloudIntegrationConfig(config: Config): BitbucketCloudIntegrationConfig;
/**
 * Reads a set of Bitbucket Cloud integration configs,
 * and inserts one for public Bitbucket Cloud if none specified.
 *
 * @param configs - All of the integration config objects
 * @public
 */
declare function readBitbucketCloudIntegrationConfigs(configs: Config[]): BitbucketCloudIntegrationConfig[];

/**
 * A Bitbucket Cloud based integration.
 *
 * @public
 */
declare class BitbucketCloudIntegration implements ScmIntegration {
    private readonly integrationConfig;
    static factory: ScmIntegrationsFactory<BitbucketCloudIntegration>;
    constructor(integrationConfig: BitbucketCloudIntegrationConfig);
    get type(): string;
    get title(): string;
    get config(): BitbucketCloudIntegrationConfig;
    resolveUrl(options: {
        url: string;
        base: string;
        lineNumber?: number;
    }): string;
    resolveEditUrl(url: string): string;
}

/**
 * The configuration parameters for a single Bitbucket API provider.
 *
 * @public
 * @deprecated bitbucket integration replaced by integrations bitbucketCloud and bitbucketServer.
 */
type BitbucketIntegrationConfig = {
    /**
     * The host of the target that this matches on, e.g. "bitbucket.org"
     */
    host: string;
    /**
     * The base URL of the API of this provider, e.g. "https://api.bitbucket.org/2.0",
     * with no trailing slash.
     *
     * Values omitted at the optional property at the app-config will be deduced
     * from the "host" value.
     */
    apiBaseUrl: string;
    /**
     * The authorization token to use for requests to a Bitbucket Server provider.
     *
     * See https://confluence.atlassian.com/bitbucketserver/personal-access-tokens-939515499.html
     *
     * If no token is specified, anonymous access is used.
     */
    token?: string;
    /**
     * The username to use for requests to Bitbucket Cloud (bitbucket.org).
     */
    username?: string;
    /**
     * Authentication with Bitbucket Cloud (bitbucket.org) is done using app passwords.
     *
     * See https://support.atlassian.com/bitbucket-cloud/docs/app-passwords/
     */
    appPassword?: string;
    /**
     * Signing key for commits
     */
    commitSigningKey?: string;
};
/**
 * Reads a single Bitbucket integration config.
 *
 * @param config - The config object of a single integration
 * @public
 * @deprecated bitbucket integration replaced by integrations bitbucketCloud and bitbucketServer.
 */
declare function readBitbucketIntegrationConfig(config: Config): BitbucketIntegrationConfig;
/**
 * Reads a set of Bitbucket integration configs, and inserts some defaults for
 * public Bitbucket if not specified.
 *
 * @param configs - All of the integration config objects
 * @public
 * @deprecated bitbucket integration replaced by integrations bitbucketCloud and bitbucketServer.
 */
declare function readBitbucketIntegrationConfigs(configs: Config[]): BitbucketIntegrationConfig[];

/**
 * A Bitbucket based integration.
 *
 * @public
 * @deprecated replaced by the integrations bitbucketCloud and bitbucketServer.
 */
declare class BitbucketIntegration implements ScmIntegration {
    private readonly integrationConfig;
    static factory: ScmIntegrationsFactory<BitbucketIntegration>;
    constructor(integrationConfig: BitbucketIntegrationConfig);
    get type(): string;
    get title(): string;
    get config(): BitbucketIntegrationConfig;
    resolveUrl(options: {
        url: string;
        base: string;
        lineNumber?: number;
    }): string;
    resolveEditUrl(url: string): string;
}

/**
 * The configuration parameters for a single Bitbucket Server API provider.
 *
 * @public
 */
type BitbucketServerIntegrationConfig = {
    /**
     * The host of the target that this matches on, e.g. "bitbucket.company.com"
     */
    host: string;
    /**
     * The base URL of the API of this provider, e.g. "https://<host>/rest/api/1.0",
     * with no trailing slash.
     *
     * The API will always be preferred if both its base URL and a token are
     * present.
     */
    apiBaseUrl: string;
    /**
     * The authorization token to use for requests to a Bitbucket Server provider.
     *
     * See https://confluence.atlassian.com/bitbucketserver/personal-access-tokens-939515499.html
     *
     * If no token is specified, anonymous access is used.
     */
    token?: string;
    /**
     * The credentials for Basic Authentication for requests to a Bitbucket Server provider.
     *
     * If `token` was provided, it will be preferred.
     *
     * See https://developer.atlassian.com/server/bitbucket/how-tos/command-line-rest/#authentication
     */
    username?: string;
    /**
     * The credentials for Basic Authentication for requests to a Bitbucket Server provider.
     *
     * If `token` was provided, it will be preferred.
     *
     * See https://developer.atlassian.com/server/bitbucket/how-tos/command-line-rest/#authentication
     */
    password?: string;
    /**
     * Signing key for commits
     */
    commitSigningKey?: string;
};
/**
 * Reads a single Bitbucket Server integration config.
 *
 * @param config - The config object of a single integration
 * @public
 */
declare function readBitbucketServerIntegrationConfig(config: Config): BitbucketServerIntegrationConfig;
/**
 * Reads a set of Bitbucket Server integration configs.
 *
 * @param configs - All of the integration config objects
 * @public
 */
declare function readBitbucketServerIntegrationConfigs(configs: Config[]): BitbucketServerIntegrationConfig[];

/**
 * A Bitbucket Server based integration.
 *
 * @public
 */
declare class BitbucketServerIntegration implements ScmIntegration {
    private readonly integrationConfig;
    static factory: ScmIntegrationsFactory<BitbucketServerIntegration>;
    constructor(integrationConfig: BitbucketServerIntegrationConfig);
    get type(): string;
    get title(): string;
    get config(): BitbucketServerIntegrationConfig;
    resolveUrl(options: {
        url: string;
        base: string;
        lineNumber?: number;
    }): string;
    resolveEditUrl(url: string): string;
}

/**
 * The configuration parameters for a single Gerrit API provider.
 *
 * @public
 */
type GerritIntegrationConfig = {
    /**
     * The host of the target that this matches on, e.g. "gerrit-review.com"
     */
    host: string;
    /**
     * The optional base URL of the Gerrit instance. It is assumed that https
     * is used and that the base path is "/" on the host. If that is not the
     * case set the complete base url to the gerrit instance, e.g.
     * "https://gerrit-review.com/gerrit". This is the url that you would open
     * in a browser.
     */
    baseUrl?: string;
    /**
     * The optional base url to use for cloning a repository. If not set the
     * baseUrl will be used.
     */
    cloneUrl?: string;
    /**
     * Disable the edit url feature for Gerrit version less than 3.9.
     */
    disableEditUrl?: boolean;
    /**
     * Base url for Gitiles. This is needed for creating a valid
     * user-friendly url that can be used for browsing the content of the
     * provider.
     */
    gitilesBaseUrl: string;
    /**
     * The username to use for requests to gerrit.
     */
    username?: string;
    /**
     * The password or http token to use for authentication.
     */
    password?: string;
    /**
     * The signing key to use for signing commits.
     */
    commitSigningKey?: string;
};
/**
 * Reads a single Gerrit integration config.
 *
 * @param config - The config object of a single integration
 *
 * @public
 */
declare function readGerritIntegrationConfig(config: Config): GerritIntegrationConfig;
/**
 * Reads a set of Gerrit integration configs.
 *
 * @param configs - All of the integration config objects
 *
 * @public
 */
declare function readGerritIntegrationConfigs(configs: Config[]): GerritIntegrationConfig[];

/**
 * A Gerrit based integration.
 *
 * @public
 */
declare class GerritIntegration implements ScmIntegration {
    private readonly integrationConfig;
    static factory: ScmIntegrationsFactory<GerritIntegration>;
    constructor(integrationConfig: GerritIntegrationConfig);
    get type(): string;
    get title(): string;
    get config(): GerritIntegrationConfig;
    resolveUrl(options: {
        url: string;
        base: string;
        lineNumber?: number;
    }): string;
    resolveEditUrl(url: string): string;
}

/**
 * The configuration parameters for a single GitHub integration.
 *
 * @public
 */
type GithubIntegrationConfig = {
    /**
     * The host of the target that this matches on, e.g. "github.com"
     */
    host: string;
    /**
     * The base URL of the API of this provider, e.g. "https://api.github.com",
     * with no trailing slash.
     *
     * May be omitted specifically for GitHub; then it will be deduced.
     *
     * The API will always be preferred if both its base URL and a token are
     * present.
     */
    apiBaseUrl?: string;
    /**
     * The base URL of the raw fetch endpoint of this provider, e.g.
     * "https://raw.githubusercontent.com", with no trailing slash.
     *
     * May be omitted specifically for GitHub; then it will be deduced.
     *
     * The API will always be preferred if both its base URL and a token are
     * present.
     */
    rawBaseUrl?: string;
    /**
     * The authorization token to use for requests to this provider.
     *
     * If no token is specified, anonymous access is used.
     */
    token?: string;
    /**
     * The GitHub Apps configuration to use for requests to this provider.
     *
     * If no apps are specified, token or anonymous is used.
     */
    apps?: GithubAppConfig[];
};
/**
 * The configuration parameters for authenticating a GitHub Application.
 *
 * @remarks
 *
 * A GitHub Apps configuration can be generated using the `backstage-cli create-github-app` command.
 *
 * @public
 */
type GithubAppConfig = {
    /**
     * Unique app identifier, found at https://github.com/organizations/$org/settings/apps/$AppName
     */
    appId: number;
    /**
     * The private key is used by the GitHub App integration to authenticate the app.
     * A private key can be generated from the app at https://github.com/organizations/$org/settings/apps/$AppName
     */
    privateKey: string;
    /**
     * Webhook secret can be configured at https://github.com/organizations/$org/settings/apps/$AppName
     */
    webhookSecret?: string;
    /**
     * Found at https://github.com/organizations/$org/settings/apps/$AppName
     */
    clientId: string;
    /**
     * Client secrets can be generated at https://github.com/organizations/$org/settings/apps/$AppName
     */
    clientSecret: string;
    /**
     * List of installation owners allowed to be used by this GitHub app. The GitHub UI does not provide a way to list the installations.
     * However you can list the installations with the GitHub API. You can find the list of installations here:
     * https://api.github.com/app/installations
     * The relevant documentation for this is here.
     * https://docs.github.com/en/rest/reference/apps#list-installations-for-the-authenticated-app--code-samples
     */
    allowedInstallationOwners?: string[];
};
/**
 * Reads a single GitHub integration config.
 *
 * @param config - The config object of a single integration
 * @public
 */
declare function readGithubIntegrationConfig(config: Config): GithubIntegrationConfig;
/**
 * Reads a set of GitHub integration configs, and inserts some defaults for
 * public GitHub if not specified.
 *
 * @param configs - All of the integration config objects
 * @public
 */
declare function readGithubIntegrationConfigs(configs: Config[]): GithubIntegrationConfig[];

/**
 * A GitHub based integration.
 *
 * @public
 */
declare class GithubIntegration implements ScmIntegration {
    private readonly integrationConfig;
    static factory: ScmIntegrationsFactory<GithubIntegration>;
    constructor(integrationConfig: GithubIntegrationConfig);
    get type(): string;
    get title(): string;
    get config(): GithubIntegrationConfig;
    resolveUrl(options: {
        url: string;
        base: string;
        lineNumber?: number;
    }): string;
    resolveEditUrl(url: string): string;
    parseRateLimitInfo(response: ConsumedResponse): RateLimitInfo;
}
/**
 * Takes a GitHub URL and replaces the type part (blob, tree etc).
 *
 * @param url - The original URL
 * @param type - The desired type, e.g. "blob"
 * @public
 */
declare function replaceGithubUrlType(url: string, type: 'blob' | 'tree' | 'edit'): string;

/**
 * The configuration parameters for a single GitLab integration.
 *
 * @public
 */
type GitLabIntegrationConfig = {
    /**
     * The host of the target that this matches on, e.g. `gitlab.com`.
     */
    host: string;
    /**
     * The base URL of the API of this provider, e.g.
     * `https://gitlab.com/api/v4`, with no trailing slash.
     *
     * May be omitted specifically for public GitLab; then it will be deduced.
     */
    apiBaseUrl: string;
    /**
     * The authorization token to use for requests to this provider.
     *
     * If no token is specified, anonymous access is used.
     */
    token?: string;
    /**
     * The baseUrl of this provider, e.g. `https://gitlab.com`, which is passed
     * into the GitLab client.
     *
     * If no baseUrl is provided, it will default to `https://${host}`
     */
    baseUrl: string;
    /**
     * Signing key to sign commits
     */
    commitSigningKey?: string;
};
/**
 * Reads a single GitLab integration config.
 *
 * @param config - The config object of a single integration
 * @public
 */
declare function readGitLabIntegrationConfig(config: Config): GitLabIntegrationConfig;
/**
 * Reads a set of GitLab integration configs, and inserts some defaults for
 * public GitLab if not specified.
 *
 * @param configs - All of the integration config objects
 * @public
 */
declare function readGitLabIntegrationConfigs(configs: Config[]): GitLabIntegrationConfig[];
/**
 * Reads a GitLab integration config, and returns
 * relative path.
 *
 * @param config - GitLabIntegrationConfig object
 * @public
 */
declare function getGitLabIntegrationRelativePath(config: GitLabIntegrationConfig): string;

/**
 * A GitLab based integration.
 *
 * @public
 */
declare class GitLabIntegration implements ScmIntegration {
    private readonly integrationConfig;
    static factory: ScmIntegrationsFactory<GitLabIntegration>;
    constructor(integrationConfig: GitLabIntegrationConfig);
    get type(): string;
    get title(): string;
    get config(): GitLabIntegrationConfig;
    resolveUrl(options: {
        url: string;
        base: string;
        lineNumber?: number;
    }): string;
    resolveEditUrl(url: string): string;
}
/**
 * Takes a GitLab URL and replaces the type part (blob, tree etc).
 *
 * @param url - The original URL
 * @param type - The desired type, e.g. 'blob', 'tree', 'edit'
 * @public
 */
declare function replaceGitLabUrlType(url: string, type: 'blob' | 'tree' | 'edit'): string;

/**
 * The configuration for a single Gitea integration.
 *
 * @public
 */
type GiteaIntegrationConfig = {
    /**
     * The host of the target that this matches on, e.g. "gitea.website.com"
     */
    host: string;
    /**
     * The optional base URL of the Gitea instance. It is assumed that https
     * is used and that the base path is "/" on the host. If that is not the
     * case set the complete base url to the gitea instance, e.g.
     * "https://gitea.website.com/". This is the url that you would open
     * in a browser.
     */
    baseUrl?: string;
    /**
     * The username to use for requests to gitea.
     */
    username?: string;
    /**
     * The password or http token to use for authentication.
     */
    password?: string;
    /**
     * Signing key to to sign commits
     */
    commitSigningKey?: string;
};
/**
 * Parses a location config block for use in GiteaIntegration
 *
 * @public
 */
declare function readGiteaConfig(config: Config): GiteaIntegrationConfig;

/**
 * A Gitea based integration.
 *
 * @public
 */
declare class GiteaIntegration implements ScmIntegration {
    readonly config: GiteaIntegrationConfig;
    static factory: ScmIntegrationsFactory<GiteaIntegration>;
    constructor(config: GiteaIntegrationConfig);
    get type(): string;
    get title(): string;
    resolveUrl(options: {
        url: string;
        base: string;
        lineNumber?: number | undefined;
    }): string;
    resolveEditUrl(url: string): string;
}

/**
 * The configuration for a single Harness integration.
 *
 * @public
 */
type HarnessIntegrationConfig = {
    /**
     * The host of the target that this matches on, e.g. "app.harness.io"
     */
    host: string;
    /**
     * The password or http token to use for authentication.
     */
    token?: string;
    /**
     * The API key to use for authentication.
     */
    apiKey?: string;
};
/**
 * Parses a location config block for use in HarnessIntegration
 *
 * @public
 */
declare function readHarnessConfig(config: Config): HarnessIntegrationConfig;

/**
 * A Harness Code based integration.
 *
 * @public
 */
declare class HarnessIntegration implements ScmIntegration {
    readonly config: HarnessIntegrationConfig;
    static factory: ScmIntegrationsFactory<HarnessIntegration>;
    constructor(config: HarnessIntegrationConfig);
    get type(): string;
    get title(): string;
    resolveUrl(options: {
        url: string;
        base: string;
        lineNumber?: number | undefined;
    }): string;
    resolveEditUrl(url: string): string;
}

/**
 * Holds all registered SCM integrations, of all types.
 *
 * @public
 */
interface ScmIntegrationRegistry extends ScmIntegrationsGroup<ScmIntegration> {
    awsS3: ScmIntegrationsGroup<AwsS3Integration>;
    awsCodeCommit: ScmIntegrationsGroup<AwsCodeCommitIntegration>;
    azureBlobStorage: ScmIntegrationsGroup<AzureBlobStorageIntergation>;
    azure: ScmIntegrationsGroup<AzureIntegration>;
    /**
     * @deprecated in favor of `bitbucketCloud` and `bitbucketServer`
     */
    bitbucket: ScmIntegrationsGroup<BitbucketIntegration>;
    bitbucketCloud: ScmIntegrationsGroup<BitbucketCloudIntegration>;
    bitbucketServer: ScmIntegrationsGroup<BitbucketServerIntegration>;
    gerrit: ScmIntegrationsGroup<GerritIntegration>;
    github: ScmIntegrationsGroup<GithubIntegration>;
    gitlab: ScmIntegrationsGroup<GitLabIntegration>;
    gitea: ScmIntegrationsGroup<GiteaIntegration>;
    harness: ScmIntegrationsGroup<HarnessIntegration>;
    /**
     * Resolves an absolute or relative URL in relation to a base URL.
     *
     * This method is adapted for use within SCM systems, so relative URLs are
     * within the context of the root of the hierarchy pointed to by the base
     * URL.
     *
     * For example, if the base URL is  `<repo root url>/folder/a.yaml`, i.e.
     * within the file tree of a certain repo, an absolute path of `/b.yaml` does
     * not resolve to `https://hostname/b.yaml` but rather to
     * `<repo root url>/b.yaml` inside the file tree of that same repo.
     */
    resolveUrl(options: {
        /**
         * The (absolute or relative) URL or path to resolve.
         */
        url: string;
        /**
         * The base URL onto which this resolution happens
         */
        base: string;
        /**
         * The line number in the target file to link to, starting with 1. Only applicable when linking to files.
         */
        lineNumber?: number;
    }): string;
    /**
     * Resolves the edit URL for a file within the SCM system.
     *
     * Most SCM systems have a web interface that allows viewing and editing files
     * in the repository. The returned URL directly jumps into the edit mode for
     * the file.
     * If this is not possible, the integration can fall back to a URL to view
     * the file in the web interface.
     *
     * @param url - The absolute URL to the file that should be edited.
     */
    resolveEditUrl(url: string): string;
}

/**
 * Default implementation of AzureCredentialsManager that supports multiple Azure Blob Storage integrations.
 * @public
 */
declare class DefaultAzureCredentialsManager implements AzureCredentialsManager {
    private readonly configProviders;
    private cachedCredentials;
    private constructor();
    /**
     * Creates an instance of DefaultAzureCredentialsManager from a Backstage integration registry.
     */
    static fromIntegrations(integrations: ScmIntegrationRegistry): DefaultAzureCredentialsManager;
    private createCredential;
    getCredentials(accountName: string): Promise<TokenCredential>;
}

/**
 * Given a URL pointing to a file on a provider, returns a URL that is suitable
 * for fetching the contents of the data.
 *
 * @remarks
 *
 * Converts
 * - from: `https://dev.azure.com/{organization}/{project}/_git/reponame?path={path}&version=GB{commitOrBranch}&_a=contents`
 * - to:   `https://dev.azure.com/{organization}/{project}/_apis/git/repositories/reponame/items?path={path}&version={commitOrBranch}`
 *
 * @param url - A URL pointing to a file
 * @public
 */
declare function getAzureFileFetchUrl(url: string): string;
/**
 * Given a URL pointing to a path on a provider, returns a URL that is suitable
 * for downloading the subtree.
 *
 * @param url - A URL pointing to a path
 * @public
 */
declare function getAzureDownloadUrl(url: string): string;
/**
 * Given a URL, return the API URL to fetch commits on the branch.
 *
 * @param url - A URL pointing to a repository or a sub-path
 * @public
 */
declare function getAzureCommitsUrl(url: string): string;

/**
 * The type of Azure DevOps credential, either bearer or pat.
 * @public
 */
type AzureDevOpsCredentialType = 'bearer' | 'pat';
/**
 * A set of credentials for Azure DevOps.
 *
 * @public
 */
type AzureDevOpsCredentials = {
    headers: {
        [name: string]: string;
    };
    token: string;
    type: AzureDevOpsCredentialType;
};
/**
 * This allows implementations to be provided to retrieve Azure DevOps credentials.
 *
 * @public
 *
 */
interface AzureDevOpsCredentialsProvider {
    getCredentials(opts: {
        url: string;
    }): Promise<AzureDevOpsCredentials | undefined>;
}

/**
 * Default implementation of AzureDevOpsCredentialsProvider.
 * @public
 */
declare class DefaultAzureDevOpsCredentialsProvider implements AzureDevOpsCredentialsProvider {
    private readonly providers;
    static fromIntegrations(integrations: ScmIntegrationRegistry): DefaultAzureDevOpsCredentialsProvider;
    private constructor();
    private forAzureDevOpsServerOrganization;
    private forAzureDevOpsOrganization;
    private forHost;
    getCredentials(opts: {
        url: string;
    }): Promise<AzureDevOpsCredentials | undefined>;
}

/**
 * Gets the request options necessary to make requests to a given provider.
 *
 * @param config - The relevant provider config
 * @param additionalHeaders - Additional headers for the request
 * @public
 * @deprecated Use {@link AzureDevOpsCredentialsProvider} instead.
 */
declare function getAzureRequestOptions(config: AzureIntegrationConfig, additionalHeaders?: Record<string, string>): Promise<{
    headers: Record<string, string>;
}>;

/**
 * Given a URL pointing to a path on a provider, returns the default branch.
 *
 * @param url - A URL pointing to a path
 * @param config - The relevant provider config
 * @public
 * @deprecated no longer in use, bitbucket integration replaced by integrations bitbucketCloud and bitbucketServer.
 */
declare function getBitbucketDefaultBranch(url: string, config: BitbucketIntegrationConfig): Promise<string>;
/**
 * Given a URL pointing to a path on a provider, returns a URL that is suitable
 * for downloading the subtree.
 *
 * @param url - A URL pointing to a path
 * @param config - The relevant provider config
 * @public
 * @deprecated no longer in use, bitbucket integration replaced by integrations bitbucketCloud and bitbucketServer.
 */
declare function getBitbucketDownloadUrl(url: string, config: BitbucketIntegrationConfig): Promise<string>;
/**
 * Given a URL pointing to a file on a provider, returns a URL that is suitable
 * for fetching the contents of the data.
 *
 * @remarks
 *
 * Converts
 * from: https://bitbucket.org/orgname/reponame/src/master/file.yaml
 * to:   https://api.bitbucket.org/2.0/repositories/orgname/reponame/src/master/file.yaml
 *
 * @param url - A URL pointing to a file
 * @param config - The relevant provider config
 * @public
 * @deprecated no longer in use, bitbucket integration replaced by integrations bitbucketCloud and bitbucketServer.
 */
declare function getBitbucketFileFetchUrl(url: string, config: BitbucketIntegrationConfig): string;
/**
 * Gets the request options necessary to make requests to a given provider.
 *
 * @param config - The relevant provider config
 * @public
 * @deprecated no longer in use, bitbucket integration replaced by integrations bitbucketCloud and bitbucketServer.
 */
declare function getBitbucketRequestOptions(config: BitbucketIntegrationConfig): {
    headers: Record<string, string>;
};

/**
 * Given a URL pointing to a path on a provider, returns the default branch.
 *
 * @param url - A URL pointing to a path
 * @param config - The relevant provider config
 * @public
 */
declare function getBitbucketCloudDefaultBranch(url: string, config: BitbucketCloudIntegrationConfig): Promise<string>;
/**
 * Given a URL pointing to a path on a provider, returns a URL that is suitable
 * for downloading the subtree.
 *
 * @param url - A URL pointing to a path
 * @param config - The relevant provider config
 * @public
 */
declare function getBitbucketCloudDownloadUrl(url: string, config: BitbucketCloudIntegrationConfig): Promise<string>;
/**
 * Given a URL pointing to a file on a provider, returns a URL that is suitable
 * for fetching the contents of the data.
 *
 * @remarks
 *
 * Converts
 * from: https://bitbucket.org/orgname/reponame/src/master/file.yaml
 * to:   https://api.bitbucket.org/2.0/repositories/orgname/reponame/src/master/file.yaml
 *
 * @param url - A URL pointing to a file
 * @param config - The relevant provider config
 * @public
 */
declare function getBitbucketCloudFileFetchUrl(url: string, config: BitbucketCloudIntegrationConfig): string;
/**
 * Gets the request options necessary to make requests to a given provider.
 *
 * @param config - The relevant provider config
 * @public
 */
declare function getBitbucketCloudRequestOptions(config: BitbucketCloudIntegrationConfig): {
    headers: Record<string, string>;
};

/**
 * Given a URL pointing to a path on a provider, returns the default branch.
 *
 * @param url - A URL pointing to a path
 * @param config - The relevant provider config
 * @public
 */
declare function getBitbucketServerDefaultBranch(url: string, config: BitbucketServerIntegrationConfig): Promise<string>;
/**
 * Given a URL pointing to a path on a provider, returns a URL that is suitable
 * for downloading the subtree.
 *
 * @param url - A URL pointing to a path
 * @param config - The relevant provider config
 * @public
 */
declare function getBitbucketServerDownloadUrl(url: string, config: BitbucketServerIntegrationConfig): Promise<string>;
/**
 * Given a URL pointing to a file on a provider, returns a URL that is suitable
 * for fetching the contents of the data.
 *
 * @remarks
 *
 * Converts
 * from: https://bitbucket.company.com/projectname/reponame/src/main/file.yaml
 * to:   https://bitbucket.company.com/rest/api/1.0/project/projectname/reponame/raw/file.yaml?at=main
 *
 * @param url - A URL pointing to a file
 * @param config - The relevant provider config
 * @public
 */
declare function getBitbucketServerFileFetchUrl(url: string, config: BitbucketServerIntegrationConfig): string;
/**
 * Gets the request options necessary to make requests to a given provider.
 *
 * @param config - The relevant provider config
 * @public
 */
declare function getBitbucketServerRequestOptions(config: BitbucketServerIntegrationConfig): {
    headers: Record<string, string>;
};

/**
 * Parse a Gitiles URL and return branch, file path and project.
 *
 * @remarks
 *
 * Gerrit only handles code reviews so it does not have a native way to browse
 * or showing the content of gits. Image if Github only had the "pull requests"
 * tab.
 *
 * Any source code browsing is instead handled by optional services outside
 * Gerrit. The url format chosen for the Gerrit url reader is the one used by
 * the Gitiles project. Gerrit will work perfectly with Backstage without
 * having Gitiles installed but there are some places in the Backstage GUI
 * with links to the url used by the url reader. These will not work unless
 * the urls point to an actual Gitiles installation.
 *
 * Gitiles url:
 * https://g.com/optional_path/\{project\}/+/refs/heads/\{branch\}/\{filePath\}
 * https://g.com/a/optional_path/\{project\}/+/refs/heads/\{branch\}/\{filePath\}
 *
 *
 * @param url - An URL pointing to a file stored in git.
 * @public
 * @deprecated `parseGerritGitilesUrl` is deprecated. Use
 *  {@link parseGitilesUrlRef} instead.
 */
declare function parseGerritGitilesUrl(config: GerritIntegrationConfig, url: string): {
    branch: string;
    filePath: string;
    project: string;
};
/**
 * Parses Gitiles urls and returns the following:
 *
 * - The project
 * - The type of ref. I.e: branch name, SHA, HEAD or tag.
 * - The file path from the repo root.
 * - The base path as the path that points to the repo root.
 *
 * Supported types of gitiles urls that point to:
 *
 * - Branches
 * - Tags
 * - A commit SHA
 * - HEAD
 *
 * @param config - A Gerrit provider config.
 * @param url - An url to a file or folder in Gitiles.
 * @public
 */
declare function parseGitilesUrlRef(config: GerritIntegrationConfig, url: string): {
    project: string;
    path: string;
    ref: string;
    refType: 'sha' | 'branch' | 'tag' | 'head';
    basePath: string;
};
/**
 * Build a Gerrit Gitiles archive url that targets a specific branch and path
 *
 * @param config - A Gerrit provider config.
 * @param project - The name of the git project
 * @param branch - The branch we will target.
 * @param filePath - The absolute file path.
 * @public
 * @deprecated `buildGerritGitilesArchiveUrl` is deprecated. Use
 *  {@link buildGerritGitilesArchiveUrlFromLocation} instead.
 */
declare function buildGerritGitilesArchiveUrl(config: GerritIntegrationConfig, project: string, branch: string, filePath: string): string;
/**
 * Build a Gerrit Gitiles archive url from a Gitiles url.
 *
 * @param config - A Gerrit provider config.
 * @param url - The gitiles url
 * @public
 */
declare function buildGerritGitilesArchiveUrlFromLocation(config: GerritIntegrationConfig, url: string): string;
/**
 * Return the authentication gitiles url.
 *
 * @remarks
 *
 * To authenticate with a password the API url must be prefixed with "/a/".
 * If no password is set anonymous access (without the prefix) will
 * be used.
 *
 * @param config - A Gerrit provider config.
 * @public
 */
declare function getGitilesAuthenticationUrl(config: GerritIntegrationConfig): string;
/**
 * Return the url to get branch info from the Gerrit API.
 *
 * @param config - A Gerrit provider config.
 * @param url - An url pointing to a file in git.
 * @public
 */
declare function getGerritBranchApiUrl(config: GerritIntegrationConfig, url: string): string;
/**
 * Return the url to clone the repo that is referenced by the url.
 *
 * @param url - An url pointing to a file in git.
 * @public
 */
declare function getGerritCloneRepoUrl(config: GerritIntegrationConfig, url: string): string;
/**
 * Return the url to fetch the contents of a file using the Gerrit API.
 *
 * @param config - A Gerrit provider config.
 * @param url - An url pointing to a file in git.
 * @public
 */
declare function getGerritFileContentsApiUrl(config: GerritIntegrationConfig, url: string): string;
/**
 * Return the url to query available projects using the Gerrit API.
 *
 * @param config - A Gerrit provider config.
 * @public
 */
declare function getGerritProjectsApiUrl(config: GerritIntegrationConfig): string;
/**
 * Return request headers for a Gerrit provider.
 *
 * @param config - A Gerrit provider config
 * @public
 */
declare function getGerritRequestOptions(config: GerritIntegrationConfig): {
    headers?: Record<string, string>;
};
/**
 * Parse the json response from Gerrit and strip the magic prefix.
 *
 * @remarks
 *
 * To prevent against XSSI attacks the JSON response body from Gerrit starts
 * with a magic prefix that must be stripped before it can be fed to a JSON
 * parser.
 *
 * @param response - An API response.
 * @public
 */
declare function parseGerritJsonResponse(response: Response): Promise<unknown>;

/**
 * Given a URL pointing to a file, returns a URL
 * for editing the contents of the data.
 *
 * @remarks
 *
 * Converts
 * from: https://gitea.com/a/b/src/branchname/path/to/c.yaml
 * or:   https://gitea.com/a/b/_edit/branchname/path/to/c.yaml
 *
 * @param url - A URL pointing to a file
 * @param config - The relevant provider config
 * @public
 */
declare function getGiteaEditContentsUrl(config: GiteaIntegrationConfig, url: string): string;
/**
 * Given a URL pointing to a file, returns an api URL
 * for fetching the contents of the data.
 *
 * @remarks
 *
 * Converts
 * from: https://gitea.com/a/b/src/branch/branchname/path/to/c.yaml
 * to:   https://gitea.com/api/v1/repos/a/b/contents/path/to/c.yaml?ref=branchname
 *
 * @param url - A URL pointing to a file
 * @param config - The relevant provider config
 * @public
 */
declare function getGiteaFileContentsUrl(config: GiteaIntegrationConfig, url: string): string;
/**
 * Given a URL pointing to a repository/path, returns a URL
 * for archive contents of the repository.
 *
 * @remarks
 *
 * Converts
 * from: https://gitea.com/a/b/src/branchname
 * or:   https://gitea.com/api/v1/repos/a/b/archive/branchname.tar.gz
 *
 * @param url - A URL pointing to a repository/path
 * @param config - The