backstage/plugins/scaffolder-backend-module-confluence-to-markdown/README.md

@backstage/plugin-scaffolder-backend-module-confluence-to-markdown

Welcome to the confluence:transform:markdown action for the scaffolder-backend.

Getting started

The following sections will help you getting started

Configure Action in Backend

From your Backstage root directory run:

# From your Backstage root directory
yarn add --cwd packages/backend @backstage/plugin-scaffolder-backend-module-confluence-to-markdown

Then configure the action: (you can check the docs to see all options):

// packages/backend/src/plugins/scaffolder.ts

import { createBuiltinActions } from '@backstage/plugin-scaffolder-backend';
import { ScmIntegrations } from '@backstage/integration';
import { createConfluenceToMarkdownAction } from '@backstage/plugin-scaffolder-backend-module-confluence-to-markdown';

export default async function createPlugin(
  env: PluginEnvironment,
): Promise<Router> {
  const catalogClient = new CatalogClient({ discoveryApi: env.discovery });
  const integrations = ScmIntegrations.fromConfig(env.config);

  const builtInActions = createBuiltinActions({
    integrations,
    catalogClient,
    config: env.config,
    reader: env.reader,
  });

  const actions = [
    ...builtInActions,
    createConfluenceToMarkdownAction({
      integrations,
      config: env.config,
      reader: env.reader,
    }),
  ];

  return createRouter({
    actions,
    catalogClient: catalogClient,
    logger: env.logger,
    config: env.config,
    database: env.database,
    reader: env.reader,
  });
}

Configuration

You will also need an access token for authorization with Read permissions. You can create a Personal Access Token (PAT) in confluence and add the PAT to your app-config.yaml

confluence:
  baseUrl: ${CONFLUENCE_BASE_URL}
  token: ${CONFLUENCE_TOKEN}

Confluence Cloud

For those using Confluence Cloud you will need to have the following configuration:

confluence:
  baseUrl: ${CONFLUENCE_BASE_URL}
  token: ${CONFLUENCE_TOKEN}
  isCloud: true

baseUrl

The baseUrl for Confluence Cloud should include the product name which is wiki by default but can be something else if your Org has changed it. An example baseUrl for Confluence Cloud would look like this: https://example.atlassian.net/wiki

token

The token for Confluence Cloud needs to be base-64 encoded with your Atlassian account email address. Here's how to do that:

1. First get your token from: https://<company-name>.atlassian.com/manage-profile/security/api-tokens
2. Next we need to setup a string in this format: <your-atlassian-account-mail>:<your-jira-token>
3. For this example we'll use this: confluence@backstage.io:wDzAzoXWRGLtvbgHvT0W
4. Now we can run echo -n "confluence@backstage.io:wDzAzoXWRGLtvbgHvT0W" | base64
5. This gives us: Y29uZmx1ZW5jZUBiYWNrc3RhZ2UuaW86d0R6QXpvWFdSR0x0dmJnSHZUMFc= which we can now use as the value for the token in the configuration

Template Usage

Here's an example of how you can use the action in your template:

apiVersion: scaffolder.backstage.io/v1beta3
kind: Template
metadata:
  name: confluence-to-markdown
  title: Confluence to Markdown
  description: This template converts a single confluence document to Markdown for Techdocs and adds it to a given GitHub repo.
  tags:
    - do-not-use
    - poc
spec:
  owner: <YOUR_EMAIL>
  type: service
  parameters:
    - title: Confluence and Github Repo Information
      properties:
        confluenceUrls:
          type: array
          description: Urls for confluence doc to be converted to markdown. In format <CONFLUENCE_BASE_URL>/display/<SPACEKEY>/<PAGE+TITLE> or <CONFLUENCE_BASE_URL>/spaces/<SPACEKEY>/pages/<PAGEID>/<PAGE+TITLE> for Confluence cloud
          items:
            type: string
            default: confluence url
          ui:options:
            addable: true
          minItems: 1
          maxItems: 5
        repoUrl:
          type: string
          title: GitHub URL mkdocs.yaml link
          description: The GitHub repo URL to your mkdocs.yaml file. Example <https://github.com/blob/master/mkdocs.yml>
  steps:
    - id: create-docs
      name: Get markdown file created and update markdown.yaml file
      action: confluence:transform:markdown
      input:
        confluenceUrls: ${{ parameters.confluenceUrls }}
        repoUrl: ${{ parameters.repoUrl }}
    - id: publish
      name: Publish PR to GitHub
      action: publish:github:pull-request
      input:
        repoUrl: <GITHUB_BASE_URL>?repo=${{ steps['create-docs'].output.repo }}&owner=${{ steps['create-docs'].output.owner }}
        branchName: confluence-to-markdown
        title: Confluence to Markdown
        description: PR for converting confluence page to mkdocs

Replace <GITHUB_BASE_URL> with your GitHub URL without https://.

You can find a list of all registered actions including their parameters at the /create/actions route in your Backstage application.