Backstage Docs Syncer

Backstage allows the addition of techdocs, using MkDocs as the orchestrating file for docs/ within a repository. The aim of this plugin is to remove the need of a docker-compose service and instead perform the syncronisation as a plugin when required.

Example Use

steps:
  - command: ls
    plugins:
      - docker-compose#v3.7.0:
          run: app
          volumes:
            - "./:/app"
      - blstrco/backstage-docs-syncer#v0.1.4:
          kind: Componenent
          entity_name: Example
          bucket: docs-hub
          namespace: secret-app

Configuration

kind (Required, string)

The Kind of the component. For more information on Kinds, visit the official documention for Backstage descriptor formats

entity_name (Required, string)

A recognisable name for your Entity, this needs to follow some conventions set out in the official documentation, but it should be something helpful that teammates can understand.

bucket (Optional, string)

The name of the S3 bucket you wish to sync the docs to, this will default to backstage-docs-bucket if not set.

namespace (Optional, string)

The ID of the namespace that the Entity belongs to, this will default to default if not set.

Caveats

• Currently there is no way to sync to a bucket not in the account that the agent is using, this may be worked around by using something like Culture Amp's Assume Role plugin to enable the agent access to a different account than the one it is in.

Development

To run the tests:

docker-compose run --rm tests

Contributing

1. Fork the repo
2. Make the changes
3. Run the tests
4. Commit and push your changes
5. Submit a pull request