Skip to content

Commit a9a98cd

Browse files
rustyjuxrustyjux
authored
APS-3957 enhance api resources, publish plugin (#3)
* Added unique naming for webservice resources, included descriptions and API entity links * Fetch API specs with UrlReaderService * Rename plugin to catalog-backend-module-bc-data-catalogue * Publish bcdc plugin to GitHub npm package registry
1 parent 70f5ca5 commit a9a98cd

13 files changed

Lines changed: 332 additions & 28 deletions

File tree

‎.github/workflows/publish-plugin.yml‎

Lines changed: 95 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,95 @@
1+
name: Publish Plugin
2+
3+
on:
4+
push:
5+
branches:
6+
- 'main'
7+
- 'feature/**'
8+
workflow_dispatch:
9+
10+
jobs:
11+
publish:
12+
runs-on: ubuntu-latest
13+
permissions:
14+
contents: write
15+
packages: write
16+
17+
steps:
18+
- name: Checkout code
19+
uses: actions/checkout@v4
20+
with:
21+
fetch-depth: 0
22+
23+
- name: Setup Node.js
24+
uses: actions/setup-node@v4
25+
with:
26+
node-version: '20'
27+
registry-url: 'https://npm.pkg.github.com'
28+
scope: '@bcgov'
29+
30+
- name: Get short commit SHA
31+
id: commit
32+
run: echo "sha8=$(git rev-parse --short=8 HEAD)" >> $GITHUB_OUTPUT
33+
34+
- name: Setup Yarn
35+
run: corepack enable && corepack prepare yarn@4.4.1 --activate
36+
37+
- name: Install dependencies
38+
run: yarn install --frozen-lockfile
39+
40+
- name: Generate TypeScript declaration files
41+
run: yarn tsc
42+
43+
- name: Determine version strategy
44+
id: version
45+
run: |
46+
CURRENT_VERSION=$(node -p "require('./plugins/catalog-backend-module-bc-data-catalogue/package.json').version")
47+
48+
if [[ "${{ github.ref }}" == refs/heads/main ]]; then
49+
# On main: increment patch version and append commit SHA
50+
# Extract base version (remove any pre-release tags)
51+
BASE_VERSION=$(echo "$CURRENT_VERSION" | sed 's/-.*//')
52+
IFS='.' read -ra VERSION_PARTS <<< "$BASE_VERSION"
53+
MAJOR=${VERSION_PARTS[0]}
54+
MINOR=${VERSION_PARTS[1]}
55+
PATCH=${VERSION_PARTS[2]}
56+
NEW_PATCH=$((PATCH + 1))
57+
NEW_VERSION="${MAJOR}.${MINOR}.${NEW_PATCH}-${{ steps.commit.outputs.sha8 }}"
58+
echo "strategy=main" >> $GITHUB_OUTPUT
59+
echo "version=${NEW_VERSION}" >> $GITHUB_OUTPUT
60+
else
61+
# On feature branches: use branch name + commit SHA
62+
# Extract base version (remove any pre-release tags)
63+
BASE_VERSION=$(echo "$CURRENT_VERSION" | sed 's/-.*//')
64+
# Sanitize branch name: remove feature/ prefix, replace invalid chars, lowercase
65+
BRANCH_NAME=$(echo "${{ github.ref_name }}" | sed 's/^feature\///' | sed 's/[^a-zA-Z0-9-]/-/g' | tr '[:upper:]' '[:lower:]')
66+
# Remove leading/trailing dashes and collapse multiple dashes
67+
BRANCH_NAME=$(echo "$BRANCH_NAME" | sed 's/^-\+//' | sed 's/-\+$//' | sed 's/-\+/-/g')
68+
NEW_VERSION="${BASE_VERSION}-${BRANCH_NAME}-${{ steps.commit.outputs.sha8 }}"
69+
echo "strategy=feature" >> $GITHUB_OUTPUT
70+
echo "version=${NEW_VERSION}" >> $GITHUB_OUTPUT
71+
fi
72+
73+
- name: Build plugin
74+
working-directory: ./plugins/catalog-backend-module-bc-data-catalogue
75+
run: yarn build
76+
77+
- name: Update package.json for publishing
78+
working-directory: ./plugins/catalog-backend-module-bc-data-catalogue
79+
run: |
80+
# Update package name to @bcgov scope
81+
npm pkg set name="@bcgov/plugin-catalog-backend-module-bc-data-catalogue"
82+
# Update version
83+
npm pkg set version="${{ steps.version.outputs.version }}"
84+
# Ensure pluginPackage is set
85+
npm pkg set backstage.pluginPackage=true
86+
# Remove private flag for publishing
87+
npm pkg delete private
88+
89+
- name: Publish to GitHub Packages
90+
working-directory: ./plugins/catalog-backend-module-bc-data-catalogue
91+
env:
92+
NODE_AUTH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
93+
run: |
94+
npm publish --access public
95+

‎app-config.yaml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -124,7 +124,7 @@ scaffolder:
124124

125125
catalog:
126126
providers:
127-
bc-data-catalogue-apis:
127+
bc-data-catalogue:
128128
env: dev
129129
import:
130130
entityFilename: catalog-info.yaml

‎packages/backend/package.json‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -40,7 +40,7 @@
4040
"@backstage/plugin-search-backend-module-techdocs": "^0.4.3",
4141
"@backstage/plugin-search-backend-node": "^1.3.12",
4242
"@backstage/plugin-techdocs-backend": "^2.0.3",
43-
"@internal/plugin-catalog-backend-module-bc-data-catalogue-apis": "workspace:^",
43+
"@internal/plugin-catalog-backend-module-bc-data-catalogue": "workspace:^",
4444
"app": "link:../app",
4545
"better-sqlite3": "^9.0.0",
4646
"node-gyp": "^10.0.0",

‎packages/backend/src/index.ts‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -52,5 +52,5 @@ backend.add(import('@backstage/plugin-search-backend-module-techdocs'));
5252
// kubernetes
5353
backend.add(import('@backstage/plugin-kubernetes-backend'));
5454

55-
backend.add(import('@internal/plugin-catalog-backend-module-bc-data-catalogue-apis'));
55+
backend.add(import('@internal/plugin-catalog-backend-module-bc-data-catalogue'));
5656
backend.start();

‎plugins/catalog-backend-module-bc-data-catalogue-apis/README.md‎

Lines changed: 0 additions & 5 deletions
This file was deleted.

plugins/catalog-backend-module-bc-data-catalogue-apis/.eslintrc.js renamed to plugins/catalog-backend-module-bc-data-catalogue/.eslintrc.js

File renamed without changes.

‎plugins/catalog-backend-module-bc-data-catalogue/README.md‎

Lines changed: 65 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,65 @@
1+
# @internal/plugin-catalog-backend-module-bc-data-catalogue
2+
3+
This plugin integrates the BC Data Catalogue with Backstage, allowing you to import datasets, resources, and their metadata as entities in Backstage's software catalogue.
4+
5+
## Installation
6+
7+
This package is published to GitHub Packages and requires authentication to install, even though it's public.
8+
9+
### Prerequisites
10+
11+
1. Create a GitHub Personal Access Token (PAT)
12+
- Go to [GitHub Settings → Developer settings → Personal access tokens → Tokens (classic)](https://github.com/settings/tokens)
13+
- Click "Generate new token (classic)"
14+
- Give it a descriptive name (e.g., "Backstage Package Access")
15+
- Select the `read:packages` scope
16+
- Give a lifespan of 90 days (or less)
17+
- **Important**: Authorize the token for SSO with the `bcgov` organization after creating it
18+
- Copy the token (you won't be able to see it again)
19+
20+
2. Set the token as an environment variable
21+
22+
```export GITHUB_TOKEN=your_token_here```
23+
24+
3. Create or update a `.npmrc` file in your project root:
25+
26+
```
27+
@bcgov:registry=https://npm.pkg.github.com
28+
//npm.pkg.github.com/:_authToken=${GITHUB_TOKEN}
29+
```
30+
**Note**: The `.npmrc` file uses environment variable substitution, so your token is stored in your environment, not in the file. This makes it safe to commit `.npmrc` to your repository.
31+
32+
### Install the Package
33+
34+
#### Using Yarn
35+
36+
yarn add @bcgov/plugin-catalog-backend-module-bc-data-catalogue
37+
38+
### Usage in Backstage
39+
40+
Add the module to your Backstage backend in `packages/backend/src/index.ts`:
41+
42+
```diff
43+
import { createBackend } from '@backstage/backend-defaults';
44+
45+
const backend = createBackend();
46+
// ... other backend.add() calls ...
47+
48+
+ backend.add(import('@bcgov/plugin-catalog-backend-module-bc-data-catalogue'));
49+
50+
backend.start();
51+
```
52+
53+
### Configure backend reading allowlist
54+
55+
Add the following configuration to your `app-config.yaml` to allow the backend to access the BC Data Catalogue API:
56+
57+
```
58+
backend:
59+
reading:
60+
allow:
61+
- host: catalogue.data.gov.bc.ca
62+
scheme: https
63+
```
64+
65+
**Note:** Additional hosts may be required depending what resources are being loaded. See https://github.com/bcgov/csit-backstage-poc/blob/main/app-config.yaml for example.

plugins/catalog-backend-module-bc-data-catalogue-apis/package.json renamed to plugins/catalog-backend-module-bc-data-catalogue/package.json

Lines changed: 4 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,9 @@
11
{
2-
"name": "@internal/plugin-catalog-backend-module-bc-data-catalogue-apis",
2+
"name": "@internal/plugin-catalog-backend-module-bc-data-catalogue",
33
"version": "0.1.0",
44
"license": "Apache-2.0",
55
"private": true,
6-
"description": "The bc-data-catalogue-apis backend module for the catalog plugin.",
6+
"description": "The bc-data-catalogue backend module for the catalog plugin.",
77
"main": "src/index.ts",
88
"types": "src/index.ts",
99
"publishConfig": {
@@ -13,7 +13,8 @@
1313
},
1414
"backstage": {
1515
"role": "backend-plugin-module",
16-
"pluginId": "catalog"
16+
"pluginId": "catalog",
17+
"pluginPackage": true
1718
},
1819
"scripts": {
1920
"start": "backstage-cli package start",

0 commit comments

Comments
 (0)