SWIRL for Backstage

Source: Confluence

This page connects Atlassian Confluence as a federated source. Confluence results appear in the Backstage search page under the swirl-federated document type.

Federated Confluence results use one credential for every portal user. Read Security first.

What you get

SWIRL ships one Confluence SearchProvider, Docs - Atlassian Confluence, inactive out of the box. It queries the Confluence content search API with CQL and returns page title, body, author, space, and labels.

Step 1: create a service account and token

Create an Atlassian account for the portal, or use an existing machine account.
Grant it read access to the spaces the portal should search, and nothing else. Confluence permissions are per space, so this is where the real limit is set.
Sign in as that account and create an API token at https://id.atlassian.com/manage-profile/security/api-tokens.
Set an expiry and note the renewal date.

Step 2: set the scope restriction

SWIRL will not activate a provider tagged Confluence unless its query carries spaceKey=, space=, or a cql= that names a space. The shipped template has the shape, with a placeholder to replace:

{url}&cql=text~'{query_string}'+and+space='<YOUR-SPACE-KEY>'

Replace the placeholder with a real space key. To search several spaces, use a CQL in clause:

{url}&cql=text~'{query_string}'+and+space in ('ENG','PLATFORM')

Step 3: edit the provider in SWIRL

Open the SWIRL admin UI at http://localhost:8000/admin/ and sign in as admin with the value you set in SWIRL_ADMIN_PASSWORD on the container. That variable is on the compose block on the install page. If it was never set, there is no password to sign in with: set it, recreate the container, and try again.

Open Search providers and click Docs - Atlassian Confluence. Edit these fields.

Field	Set it to
URL	Replace `<your-domain>` with your Atlassian site name, in both the URL and the result mappings.
Query template	The scoped CQL template from step 2.
Credentials	`HTTPBasicAuth('service-account@example.com','<api-token>')`, using the account email and the token from step 1. The field is masked once saved, so it shows a placeholder rather than the token. Retyping it replaces it; leaving it alone keeps it.
Tags	Confirm `backstage` is present, so the engine module fans out to this provider.
Active	Tick it. Saving with an unscoped query is refused here.

Or via the API

The same change over HTTP, for a bootstrap script or a CI job. SWIRL requires a CSRF cookie and header on a write even when the request carries a token, so fetch the cookie first. The provider id is in the admin URL and in the list response.

csrf=$(curl -s -c jar http://localhost:8000/admin/login/ -o /dev/null; grep csrftoken jar | awk '{print $NF}')
curl -X PATCH http://localhost:8000/swirl/sapi/searchproviders/<provider-id>/ \
  -H "Authorization: Token <admin-api-token>" \
  -H "Content-Type: application/json" \
  -H "X-CSRFToken: $csrf" -H "Cookie: csrftoken=$csrf" \
  -H "Referer: http://localhost:8000/swirl/sapi/searchproviders/<provider-id>/" \
  -d '{"credentials":"HTTPBasicAuth(\'service-account@example.com\',\'<token>\')","active":true}'

Two things to know. The write path is /swirl/sapi/searchproviders/; /swirl/searchproviders/ answers 403 to a token. And a token on its own, with no CSRF cookie and header, is refused with {"detail":"CSRF Failed: CSRF cookie not set."}.

The result mappings also contain <your-domain>, in the expression that builds each result URL. Replace it there too, or result links will not resolve.

Step 4: test with one search

curl -s -H "Authorization: Token <admin-api-token>" \
    "http://localhost:8000/swirl/search/?qs=onboarding&providers=backstage"

Check the messages array for the Confluence provider and its result count. Then run the same term in Backstage and look for results typed swirl-federated.

Other sources

GitHub is the other source in this release, on its own page. Jira, GitLab, and further sources are planned, with no dates set. SWIRL connects to many sources beyond these two; see the SearchProvider Guide.