https://github.com/microcks/microcks-backstage-provider
A provider for Backstage.io allowing to synchronize API entities from Microcks to Backstage
https://github.com/microcks/microcks-backstage-provider
api backstage backstage-plugin contract-testing microcks mocking
Last synced: 5 months ago
JSON representation
A provider for Backstage.io allowing to synchronize API entities from Microcks to Backstage
- Host: GitHub
- URL: https://github.com/microcks/microcks-backstage-provider
- Owner: microcks
- License: apache-2.0
- Created: 2023-01-04T13:26:21.000Z (about 3 years ago)
- Default Branch: main
- Last Pushed: 2025-09-26T09:46:40.000Z (5 months ago)
- Last Synced: 2025-10-01T18:36:07.332Z (5 months ago)
- Topics: api, backstage, backstage-plugin, contract-testing, microcks, mocking
- Language: TypeScript
- Homepage: https://microcks.io
- Size: 2.05 MB
- Stars: 9
- Watchers: 3
- Forks: 6
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
- Security: SECURITY-INSIGHTS.yml
- Governance: GOVERNANCE.md
- Roadmap: ROADMAP.md
- Maintainers: MAINTAINERS.md
Awesome Lists containing this project
README
# Microcks Backstage provider
[](https://github.com/microcks/microcks-backstage-provider/actions)
[]((https://search.maven.org/artifact/io.github.microcks/microcks))
[](https://www.apache.org/licenses/LICENSE-2.0)
[](https://microcks.io/discord-invite/)
[](https://artifacthub.io/packages/search?repo=microcks)
[](https://landscape.cncf.io/?item=app-definition-and-development--application-definition-image-build--microcks)
This is a plugin for synchronizing Microcks content into [Backstage.io](https://backstage.io/) catalog.
The `microcks-backstage-provider` has a special entity provider for discovering catalog [API entities](https://backstage.io/docs/features/software-catalog/system-model#api) defined in one or many Microcks instances. If you're using Microcks to discover APIs from your Git repositories, auto-publish smart mock endpoints and realize contract testing of your components, this provider can synchronize the API definitions from Microcks into your Backstage intance.
## Build Status
Latest released version is `0.0.7`.
Current development version is `0.0.8-SNAPSHOT`.
#### Fossa license and security scans
[](https://app.fossa.com/projects/git%2Bgithub.com%2Fmicrocks%2Fmicrocks-backstage-provider?ref=badge_shield&issueType=license)
[](https://app.fossa.com/projects/git%2Bgithub.com%2Fmicrocks%2Fmicrocks-backstage-provider?ref=badge_shield&issueType=security)
[](https://app.fossa.com/projects/git%2Bgithub.com%2Fmicrocks%2Fmicrocks-backstage-provider?ref=badge_small)
#### OpenSSF best practices on Microcks core
[](https://bestpractices.coreinfrastructure.org/projects/7513)
[](https://securityscorecards.dev/viewer/?uri=github.com/microcks/microcks)
## Community
* [Documentation](https://microcks.io/documentation/tutorials/getting-started/)
* [Microcks Community](https://github.com/microcks/community) and community meeting
* Join us on [Discord](https://microcks.io/discord-invite/), on [GitHub Discussions](https://github.com/orgs/microcks/discussions) or [CNCF Slack #microcks channel](https://cloud-native.slack.com/archives/C05BYHW1TNJ)
To get involved with our community, please make sure you are familiar with the project's [Code of Conduct](./CODE_OF_CONDUCT.md).
## Versions
| Basckstage Client | Microcks Backstage provider Version |
|-------------------|------------------|
| `>= 1.43` | `0.0.7` and + |
| `>= 1.31 && <1.43`| `0.0.6` and + |
| `< 1.31` | `0.0.5` |
## Screenshots
Your Services and API from different Microcks instances can be discovered and imported into your Backstage catalog.
Labels on your API in Microcks are be translated onto Backstage systems and owners. The plugin add links to access the API mock endpoints and conformance tests results.
## Install
After having created a new backstage app like described in Backstage.io' [Getting Started](https://backstage.io/docs/getting-started/#create-your-backstage-app), enter the app directory and run this command to add the Microcks Entity provider as a new backend plugin:
```sh
yarn --cwd packages/backend add @microcks/microcks-backstage-provider@^0.0.7
```
## Configure
Microcks Backstage provider allows configuration of one or many providers using the `app-config.yaml` configuration file of Backstage. Use a `microcksApiEntity` marker to start configuring them.
Each children key (here `dev` in the following sample) configures a provider for a specific `lifecyle` phase of your Entities so you may discover `API` entities from different Microcks instances.
At your configuration, you add a provider config per liefcycle:
```yaml
# app-config.yaml
catalog:
providers:
microcksApiEntity:
dev:
baseUrl: https://microcks.acme.com
serviceAccount: microcks-serviceaccount
serviceAccountCredentials: ab54d329-e435-41ae-a900-ec6b3fe15c54
systemLabel: domain
ownerLabel: team
addLabels: false # optional; copy any other labels from Microcks in Backstage catalog - default is true
addOpenAPIServerUrl: true # optional; add a server in OpenAPI spec to point to Microcks sandbox URL - default is false
schedule: # optional; same options as in TaskScheduleDefinition
# supports cron, ISO duration, "human duration" as used in code
frequency: { minutes: 2 }
# supports ISO duration, "human duration" as used in code
timeout: { minutes: 1 }
```
Configuration is pretty straightforward but your may check Microcks documentation on [Service Accounts](https://microcks.io/documentation/automating/service-account/) for details.
Once you've done that, you'll also need to declare the Microcks as a backend module or an available entity provider. This operation differs depending on the version of Backstage you're using.
### For Backstage versions with the new Backend system
> Typically for application created via the CLI starting with Backstage `1.24`
You'll need to add the Microcks backend module in the `packages/backend/src/index.ts` file, before the `backend.start()` directive. Use this snippet below:
```ts
// microcks catalog provider
backend.add(import('@microcks/microcks-backstage-provider'));
```
### For Backstage versions with the old Backend plugin system
You need add the segment below to `packages/backend/src/plugins/catalog.ts`:
```ts
/* packages/backend/src/plugins/catalog.ts */
import { MicrocksApiEntityProvider } from '@microcks/microcks-backstage-provider';
[...]
const builder = await CatalogBuilder.create(env);
/** ... other processors and/or providers ... */
builder.addEntityProvider(
MicrocksApiEntityProvider.fromConfig(env.config, {
logger: env.logger,
scheduler: env.scheduler
}),
);
const { processingEngine, router } = await builder.build();
[...]
```
## Troubleshoot
After having started your Backstage app, you should see some lines like those below in logs:
```log
[1] 2023-01-04T16:07:47.630Z catalog info Keycloak authentication is not enabled, using a fake token. type=plugin target=MicrocksApiEntityProvider:dev
[1] 2023-01-04T16:07:47.699Z catalog info Discovered ApiEntity API Pastry - 2.0 - 2.0.0 type=plugin target=MicrocksApiEntityProvider:dev
[1] 2023-01-04T16:07:47.708Z catalog info Discovered ApiEntity Account Service - 1.1.0 type=plugin target=MicrocksApiEntityProvider:dev
[1] 2023-01-04T16:07:47.712Z catalog info Discovered ApiEntity HelloService - v1 type=plugin target=MicrocksApiEntityProvider:dev
[1] 2023-01-04T16:07:47.728Z catalog info Discovered ApiEntity User signed-up API - 0.1.1 type=plugin target=MicrocksApiEntityProvider:dev
[1] 2023-01-04T16:07:47.734Z catalog info Discovered ApiEntity User signed-up API - 0.1.20 type=plugin target=MicrocksApiEntityProvider:dev
[1] 2023-01-04T16:07:47.740Z catalog info Discovered ApiEntity User signed-up API - 0.1.30 type=plugin target=MicrocksApiEntityProvider:dev
[1] 2023-01-04T16:07:47.745Z catalog info Discovered ApiEntity User signed-up Avro API - 0.1.2 type=plugin target=MicrocksApiEntityProvider:dev
[1] 2023-01-04T16:07:47.749Z catalog info Applying the mutation with 7 entities type=plugin target=MicrocksApiEntityProvider:dev
```
## Build and release
After a fresh `git clone`, you can install dependencies, compile typescript and build a new distribution with those commands:
```sh
$ yarn install && yarn tsc && yarn export-dynamic && yarn run build
```
When publishing a release withe the `release` GitHub Action, generating the SBOM from Yarn files fails because of unresolved transitive dependencies. So we included `package-lock.json` and generate the SBOM with the `--package-lock-only` flag.
> So, whenever you update a dependency in `package.json` and then `yarn.lock`, please ensure that you also update `package-lock.json` otherwise the next release will fail!
## Develop locally
After having created a new backstage app like described in Backstage.io' [Getting Started](https://backstage.io/docs/getting-started/#create-your-backstage-app), just edit the `packages/backend/src/plugins/catalog.ts` file and apply same configuration as above insdtallation directive but with relative path to your local clone of this repository:
```ts
/* packages/backend/src/plugins/catalog.ts */
import { MicrocksApiEntityProvider } from '../../../../../github/microcks-backstage-provider';
```
Just launch your local backstage app using `yarn dev` at the root folder level.