Skip to content

Commit 9fb3f88

Browse files
janstaelensskylinejanstaelensskyline
authored
Create README.md
1 parent 29723dc commit 9fb3f88

File tree

1 file changed

+132
-0
lines changed

1 file changed

+132
-0
lines changed

‎README.md

+132
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,132 @@
1+
# Skyline.DataMiner.CICD.Tools.GitHubToCatalogYaml
2+
3+
## Overview
4+
5+
The **Skyline.DataMiner.CICD.Tools.GitHubToCatalogYaml** tool automates the creation or updating of a `catalog.yml` file based on a GitHub repository's metadata. This file, which can be automatically generated and maintained by this tool, serves as the primary input for [registering an item to the DataMiner Catalog](https://docs.dataminer.services/user-guide/Cloud_Platform/Catalog/Register_Catalog_Item.html). By extracting essential metadata from GitHub, such as descriptions, tags, and topics, this tool ensures that catalog entries align with the latest repository information, streamlining the process of catalog registration and maintenance within DataMiner's ecosystem.
6+
7+
## Key Features
8+
9+
- **Metadata Extraction**: Retrieves essential information (description, tags, repository URL) from GitHub to populate `catalog.yml`.
10+
- **Type Inference**: Detects artifact type from repository naming conventions or GitHub topics.
11+
- **Automatic Catalog Updates**: Creates or extends `catalog.yml` with up-to-date repository data.
12+
13+
## GitHub UI Mappings to `catalog.yml` Fields
14+
15+
| **GitHub UI** | **`catalog.yml` Field** | **Description** |
16+
|--------------------------------|-------------------------|-----------------------------------------------------------------------------------------------------------------|
17+
| Repository Name | `Title` | Used as the title if no title is set in `catalog.yml`. |
18+
| Description | `ShortDescription` | Fetched from the repository’s description, if not provided in `catalog.yml`. |
19+
| Topics | `Tags` | GitHub topics are added as tags for the catalog item. |
20+
| URL | `SourceCodeUrl` | Generated as `https://github.com/{owner}/{repo}`, if missing in `catalog.yml`. |
21+
| Variable: `CATALOGIDENTIFIER` | `Id` | If not specified in the existing YAML or as a variable, an identifier is generated automatically for each catalog entry. |
22+
| Owners | `Owners` | Customizable, with owner email, name, and URL settings. |
23+
24+
## Auto-Generated Catalog YAML File
25+
26+
This tool not only extends an existing `catalog.yml` or `manifest.yml` but also generates an `auto-generated-catalog.yml` file in the `.githubtocatalog` directory. This secondary file is essential because:
27+
28+
1. **Tracking Catalog IDs**: By committing and pushing `auto-generated-catalog.yml`, the tool can create a unique ID on the first run and reuse this ID on future runs. This avoids duplicate catalog records that can occur if new IDs are generated in every workflow run.
29+
2. **Workflow Automation**: The `auto-generated-catalog.yml` is maintained separately to allow other processes to retrieve it as needed without modifying the primary catalog file in each update.
30+
31+
## Inferring Catalog Item Type
32+
33+
The tool can infer the artifact type in two ways:
34+
35+
1. **Repository Naming Convention**: Follows the [GitHub Repository Naming Convention](https://docs.dataminer.services/develop/CICD/Skyline%20Communications/Github/Use_Github_Guidelines.html#repository-naming-convention) to infer the type from the repository name.
36+
37+
2. **GitHub Topic**: If the repository does not follow the naming convention, the tool relies on a GitHub topic that corresponds to one of the recognized artifact types.
38+
39+
If neither condition is met, the workflow will fail, and an error will be returned.
40+
41+
### Artifact Types
42+
43+
- **AS**: `automationscript`
44+
- **C**: `connector`
45+
- **CF**: `companionfile`
46+
- **CHATOPS**: `chatopsextension`
47+
- **D**: `dashboard`
48+
- **DISMACRO**: `dismacro`
49+
- **DOC**: `documentation`
50+
- **F**: `functiondefinition`
51+
- **GQIDS**: `gqidatasource`or `adhocdatasource`
52+
- **GQIO**: `gqioperator`
53+
- **LSO**: `lifecycleserviceorchestration`
54+
- **PA**: `processautomation`
55+
- **PLS**: `profileloadscript`
56+
- **S**: `solution`
57+
- **SC**: `scriptedconnector`
58+
- **T**: `testingsolution`
59+
- **UDAPI**: `userdefinedapi`
60+
- **V**: `visio`
61+
62+
## Installation & Usage
63+
64+
### Prerequisites
65+
66+
Ensure you have [.NET](https://dotnet.microsoft.com/download) installed to run the tool.
67+
68+
### Installation
69+
70+
Install the tool via the terminal:
71+
72+
```bash
73+
dotnet tool install -g Skyline.DataMiner.CICD.Tools.GitHubToCatalogYaml
74+
```
75+
76+
### Running the Tool
77+
78+
Execute the tool using the following command and options:
79+
80+
```bash
81+
github-to-catalog-yaml --workspace "/path/to/workspace" --github-token "your_token" --github-repository "owner/repo"
82+
```
83+
84+
### Command Options
85+
86+
- `--workspace` (required): Path to where `catalog.yml` is located or will be created.
87+
- `--github-token` (required): GitHub token (Personal Access Token or `secrets.GITHUB_TOKEN`).
88+
- `--github-repository` (required): GitHub repository name in the format `owner/repo`.
89+
- `--debug` (optional): Enable debug logging for detailed output.
90+
91+
## Example Usage in GitHub Workflow
92+
93+
Below is an example workflow for using this tool to automate catalog management in GitHub Actions. Refer to [Automation Master SDK Workflow](https://github.com/SkylineCommunications/_ReusableWorkflows/blob/main/.github/workflows/Automation%20Master%20SDK%20Workflow.yml) for a complete setup.
94+
95+
```yaml
96+
auto_generate_catalog_yaml:
97+
name: Auto-Generating Catalog from GitHub
98+
if: inputs.referenceType == 'branch'
99+
runs-on: ubuntu-latest
100+
steps:
101+
- name: Install .NET Tools
102+
run: |
103+
dotnet tool install -g Skyline.DataMiner.CICD.Tools.GitHubToCatalogYaml --prerelease
104+
105+
- name: Create or Extend Catalog.yml
106+
run: |
107+
github-to-catalog-yaml --workspace "${{ github.workspace }}" --github-token ${{ secrets.GITHUB_TOKEN }} --github-repository "${{ github.repository }}" --catalog-identifier "${{ vars.catalogIdentifier }}"
108+
109+
- name: Commit .githubtocatalog/auto-generated-catalog
110+
shell: pwsh
111+
run: |
112+
git config --global user.name "github-actions[bot]"
113+
git config --global user.email "github-actions[bot]@users.noreply.github.com"
114+
git add "${{ github.workspace }}/.githubtocatalog/auto-generated-catalog.yml"
115+
116+
# Check if there are any changes to be committed
117+
git diff --staged --quiet
118+
if ($LASTEXITCODE -ne 0) {
119+
git commit -m "auto-generated"
120+
}
121+
else {
122+
Write-Host "No changes to commit."
123+
}
124+
125+
- name: Push .githubtocatalog/auto-generated-catalog
126+
run: |
127+
git push
128+
env:
129+
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
130+
```
131+
132+
This workflow installs the **Skyline.DataMiner.CICD.Tools.GitHubToCatalogYaml** tool, generates or extends the `catalog.yml`, and pushes any updates in `.githubtocatalog/auto-generated-catalog.yml` to avoid duplicate catalog entries.

0 commit comments

Comments
 (0)