|
1 | | -# Notion Github Catalog |
2 | | - |
3 | | -This action will scan all of the Github repositories available to the provided token and update their information in the specified Notion database. |
4 | | - |
5 | | -TL;DR ... you love the idea of https://backstage.io/ but think its way too complex to manage and operate, so just use Notion instead :) |
6 | | - |
7 | | -## Notion integration and token |
8 | | - |
9 | | -First, you need to have an integration access token - which you can get from https://www.notion.so/my-integrations after creating an integration. Give the integration a friendly name like 'Github Actions'. |
10 | | - |
11 | | -By default integrations cant access any content so you you *must* share your database (or the parent page / tree it is contained within) with the integration you created earlier to be able to access it. |
12 | | - |
13 | | -## Notion Databases |
14 | | - |
15 | | -This action expects a Notion database with the following properties, this will become the |
16 | | - |
17 | | - - Name: text |
18 | | - - Description: text |
19 | | - - Kind: select |
20 | | - - Lifecycle: select |
21 | | - - URL: url |
22 | | - - Owner: select|relation |
23 | | - - System: select|relation |
24 | | - - DependsOn: relation (to self - new field - sync tasks) |
25 | | - - Tags: multi_select |
26 | | - - Visibility: select |
27 | | - - Language: select |
28 | | - - Status: select |
29 | | - - Updated: date |
30 | | - - Hash: text |
31 | | - |
32 | | -The following notion page and database is connected to the tests by default, and can be used as a template: https://infinitaslearning.notion.site/Notion-Github-Catalogue-ac2395eda37144e698e6b8faef1003c7 |
33 | | - |
34 | | -It looks like this after it has run: |
35 | | - |
36 | | -<img width="1451" alt="Screenshot 2021-12-19 at 12 55 39" src="https://user-images.githubusercontent.com/239305/146673989-01187d53-d2fd-42ba-9968-31442b8cc92d.png"> |
37 | | - |
38 | | -### Embedded Data |
39 | | - |
40 | | -If your descriptor file contains links, these are added to an embedded database within the service page called `Links`. |
41 | | - |
42 | | -## Relation Databases |
43 | | - |
44 | | -You have an option to provide additional 'lookup' databases to convert some of the above selects into relations: |
45 | | - |
46 | | -### Owner, System |
47 | | - |
48 | | -1. Create a database that has *at least* a `Name` column that is unique, all other columns are up to you. |
49 | | -2. Create an 'Unknown' row - this is what services that cannot be mapped go to (this name matters). |
50 | | -3. In the config of the action, provide the input variable `owner_database` pointing to this database. |
51 | | -4. In the main service catalogue table convert the `Owner` column to a relation, pointing at the above database. |
52 | | - |
53 | | -This can be repeated for `System`. The full config is below in the usage. |
54 | | - |
55 | | -## Service Descriptor Format |
56 | | - |
57 | | -This action expects each of your repositories to have a descriptor file format in the root of the repo in the form of a Backstage `catalog-info` file. This is because we are testing this approach against using Backstage directly, and wanted to leverage a format that perhaps has a chance of becoming a defacto standard. It does not currently map all fields from Backstage, but if you look at the code you can see what it does map. I may add a config option to allow mapping to be more dynamic in future (a good PR!). |
58 | | - |
59 | | -Information on the format: https://backstage.io/docs/features/software-catalog/descriptor-format |
60 | | - |
61 | | -The following types are supported: |
62 | | - |
63 | | -### Component |
64 | | - |
65 | | -This is a basic component, with the following fields supported: |
66 | | - |
67 | | -``` |
68 | | -apiVersion: backstage.io/v1alpha1 |
69 | | -kind: Component |
70 | | -metadata: |
71 | | - name: app-ecommerce-web |
72 | | - description: The front end application for noordhoff.nl, plantyn.com and liber.se |
73 | | - links: |
74 | | - - url: https://portal.azure.com/#@infinitaslearning.onmicrosoft.com/resource/subscriptions/4ebd66c4-aaad-4b1b-bb4e-740db9f1fc4d/resourceGroups/ecommerce-pro-rg/overview |
75 | | - title: Azure |
76 | | - icon: dashboard |
77 | | - - url: https://liber-shop.production.infinicloud.app/ |
78 | | - title: Production |
79 | | - tags: |
80 | | - - ecommerce |
81 | | - - application |
82 | | - - react |
83 | | -spec: |
84 | | - type: application |
85 | | - lifecycle: production |
86 | | - owner: commercial |
87 | | - system: ecommerce |
88 | | - dependsOn: |
89 | | - - service-cms-api |
90 | | -``` |
91 | | - |
92 | | -Fields other than those above are currently not supported, but could be with a PR. |
93 | | - |
94 | | -### API |
95 | | - |
96 | | -This can be used, though we do not support the `spec` attribute, as it is impossible to render things like OpenAPI inside Notion, so these should be linked to via the links, but if you create a file exactly as *Component* above, it will be processed with the different `Kind` property (so be filterable). |
97 | | - |
98 | | -### Location |
99 | | - |
100 | | -This should be used in the case of a mono-repo, that contains multile sub-components. Place the following in the root. Note that in the current implementation it needs to be a relative path to the root of the repository, and do not start paths with `./`. No information from the Location file itself is added to the catalog, only the linked targets. |
101 | | - |
102 | | -``` |
103 | | -apiVersion: backstage.io/v1alpha1 |
104 | | -kind: Location |
105 | | -spec: |
106 | | - type: url |
107 | | - targets: |
108 | | - - sub-component-one/catalog-info.yaml |
109 | | - - sub-component-two/catalog-info.yaml |
110 | | -``` |
111 | | - |
112 | | -## Usage |
113 | | - |
114 | | -This is typically deployed as a scheduled action: |
115 | | - |
116 | | -```yaml |
117 | | -name: Catalog |
118 | | -on: |
119 | | - schedule: |
120 | | - - cron: '30 5 * * *' |
121 | | - workflow_dispatch: |
122 | | -jobs: |
123 | | - catalog: |
124 | | - runs-on: ubuntu-latest |
125 | | - steps: |
126 | | - - name: Notion github catalog |
127 | | - uses: infinitaslearning/notion-github-catalog@main |
128 | | - with: |
129 | | - github_owner: infinitaslearning |
130 | | - github_token: ${{ secrets.PAT_GITHUB_TOKEN }} |
131 | | - notion_token: ${{ secrets.NOTION_TOKEN }} |
132 | | - database: 2b26b4290cc84d95ad3e93c3255277a1 |
133 | | - owner_database: 7943615f4dba43b3a3b0f991f4f7136d |
134 | | - system_database: 121534684fe840a1953500e603c2b602 |
135 | | - repository_type: all |
136 | | - repository_filter: .* |
137 | | - push_missing: true |
138 | | - catalog_file: catalog-info.yaml |
139 | | - |
140 | | -``` |
141 | | - |
142 | | -To get the database ID, simply browse to it, click on the '...' in Notion, and get a 'Copy link'. The GUID at the end of the URL (but before the `?v=`) is the id, this works on both embedded and full page databases. |
143 | | - |
144 | | -## Development |
145 | | - |
146 | | -Assumes you have `@vercel/ncc` installed globally. |
147 | | -After changes ensure you `npm run build`, commit and then submit a PR. |
148 | | - |
149 | | -For the tests to run you need to have the environment variables set for GITHUB_TOKEN, NOTION_TOKEN and NOTION_DATABASE. |
| 1 | +# Notion Azure Catalog |
0 commit comments