Create gitlab register component template

templates/github/register-github-component/README.md

@@ -0,0 +1,88 @@
+# Register existing component to Service Catalog
+
+This template is intended to be used as a starting point for registering an existing github repository to the Service Catalog. Both github.com and GitHub Enterprise are supported.
+
+## Prerequisites
+
+- Ensure the github host is added to the `app-config.yaml` file in the backstage instance
+- If using a github enterprise instance, make sure the `apiBaseUrl` is set correctly:
+
+  ```yaml
+  integrations:
+    gitlab:
+      - host: github.mycompany.com # this must match the hostname of your gitlab instance
+        token: my-github-token # You can use a token or a github app (app will take precedence)
+        apps:
+          - appId: app-id
+            clientId: client-id
+            clientSecret: client-secret
+            webhookSecret: webhook-secret
+            privateKey: |
+              -----BEGIN RSA PRIVATE KEY-----
+              ...Key content...
+              -----END RSA PRIVATE KEY-----
+        apiBaseUrl: https://github.mycompany.com/api/v3 # This field is optional if host is `github.com`
+        # apiBaseUrl: https://api.github.mycompany.com # This is also a potential api base url for github enterprise
+  ```
+
+### Required GitHub permissions
+
+The GitHub application or access token needs to have the following permissions:
+
+- **Repository permissions**
+
+  - **Contents**: **_Read & write_** - To be able to create a new branch and push files new `catalog-info.yaml` file into it.
+  - **Pull requests**: **_Read & write_** - To be able to create pull requests with generated `catalog-info.yaml`.
+  - **Commit statuses**: **_Read-only_** - To be able to clone private repositories.
+
+## Usage
+
+![github-location-info-image](./images/github-location-info.png)
+
+- `GitHub hostname`: The hostname of your github instance
+  - Default value: `github.com`
+  - For Github Free, Pro & Team, use `github.com`
+  - For Github Enterprise, use the hostname of your instance. e.g. `github.mycompany.com`
+  - **NOTE**: this hostname MUST exist in the github integrations in the backstage instance's `app-config.yaml` with the correct access token or github app
+- `Github Organization`: The owner of the repository (user or organization)
+- `Repository name`: The name of the repository where your component is located
+
+![github-component-info-image](./images/github-component-info.png)
+
+- `Component Name` (Optional): The name used to identify the component in the backstage catalog
+  - **NOTE**: this name also must adhere to the backstage entity name format [requirements](https://github.com/backstage/backstage/blob/master/docs/architecture-decisions/adr002-default-catalog-file-format.md#name).
+  - Additionally, this name should not already be in use in the backstage catalog
+  - If left blank, the value of `Repository name` will be used instead
+    - If the value of `Repository name` is used, then it must also adhere to these requirements,
+  - If these requirements are not met, the component will not be ingested properly.
+  - Used to populate the [`metadata.name`](https://backstage.io/docs/features/software-catalog/descriptor-format/#specowner-required) field of the component's `catalog-info.yaml`
+- `Owner`: The owner of the component in the backstage catalog
+
+  - Expects a `User` or `Group` entity in the backstage catalog
+  - This value is inputted via a dropdown menu, and will only show users and groups that already exist in the backstage catalog
+  - This template will not function correctly if no `User` or `Group` entities exist in the backstage catalog
+  - Used to populate the [`spec.owner`](https://backstage.io/docs/features/software-catalog/descriptor-format/#specowner-required) field of the component's `catalog-info.yaml`
+
+- `Type`: The type of component in the backstage catalog
+  - Default value: `other`
+  - Well-known and common values: service, website, library.
+  - Used to populate the [`spec.type`](https://backstage.io/docs/features/software-catalog/descriptor-format#spectype-required) field of the component's `catalog-info.yaml`
+- `Lifecycle`: The lifecycle stage of the component in the backstage catalog
+  - Default value: `unknown`
+  - Well-known and common values include: experimental, production, deprecated.
+  - Used to populate the [`spec.lifecycle`](https://backstage.io/docs/features/software-catalog/descriptor-format/#speclifecycle-required) field of the component's `catalog-info.yaml`
+
+Once all these values are filled in, you should see a summary screen with all your inputted values.
+![github-summary-image](./images/github-summary.png)
+
+### Expected Output
+
+![gpt-result-image](./images/gpt-result.png)
+Once you press create, you should expect all the steps to be completed successfully and the component registered, but not ingested yet.
+
+To ingest the component, you will need to merge the pull request created by the template.
+To navigate to the pull request, click the `Go to PR #{PR_NUMBER}` button to be redirected to the corresponding pull request.
+Feel free to add any additional annotations to the `catalog-info.yaml` file before merging the pull request.
+Once the pull request is merged, wait up to 5 minutes for the component to be ingested into the catalog.
+
+Once ingested, navigate to the catalog (filter by `kind=Component`) and you should see your newly registered component.

templates/github/register-component/template.yaml → templates/github/register-github-component/template.yaml

@@ -1,8 +1,8 @@
 apiVersion: scaffolder.backstage.io/v1beta3
 kind: Template
 metadata:
-  name: register-component
-  title: Register existing component to Software Catalog
+  name: register-github-component
+  title: Register existing component to Software Catalog from Github
   description: Registers existing component (GitHub repository) to Software Catalog
   tags:
     - import
@@ -41,7 +41,10 @@ spec:
         componentName:
           title: Component Name
           type: string
-          description: Name of the created component. If leaved empty the name of the repository will be used.
+          description: Name of the created component. If left empty the name of the repository will be used.
+          # Refer to https://github.com/backstage/backstage/blob/master/docs/architecture-decisions/adr002-default-catalog-file-format.md#name
+          maxLength: 63
+          pattern: ^([A-Za-z0-9][-A-Za-z0-9_.]*)?[A-Za-z0-9]$
         componentOwner:
           title: Owner
           description: Select an owner from the list or enter a reference to a Group or a User
@@ -55,12 +58,12 @@ spec:
         componentType:
           title: Type
           type: string
-          description: 'The type of component. Well-known and common values: service, website, library.'
+          description: "The type of component. Well-known and common values: service, website, library."
           default: other
         componentLifecycle:
           title: Lifecycle
           type: string
-          description: 'The lifecycle state of the component. Well-known and common values: experimental, production, deprecated.'
+          description: "The lifecycle state of the component. Well-known and common values: experimental, production, deprecated."
           default: unknown
 
   steps:
@@ -108,5 +111,5 @@ spec:
 
   output:
     links:
-      - title: 'Open PR #${{ steps.publishPR.output.pullRequestNumber }}'
+      - title: "Open PR #${{ steps.publishPR.output.pullRequestNumber }}"
         url: ${{ steps.publishPR.output.remoteUrl }}

templates/gitlab/register-gitlab-component/README.md

@@ -0,0 +1,79 @@
+# Register existing component to Service Catalog
+
+This template is intended to be used as a starting point for registering an existing gitlab project to the Service Catalog. Both `gitlab.com` and Gitlab for Enterprise are supported.
+
+## Prerequisites
+
+- Ensure the gitlab host is added to the `app-config.yaml` file in the backstage instance
+- If using a private Gitlab instance, make sure the `apiBaseUrl` is set correctly:
+
+  ```yaml
+  integrations:
+    gitlab:
+      - host: gitlab.mycompany.com # this must match the hostname of your gitlab instance
+        token: my-gitlab-token
+        apiBaseUrl: https://gitlab.mycompany.com/api/v4 # This field is optional if host is `gitlab.com`
+  ```
+
+- Make sure that the `add-catalog-info` branch and `catalog-info.yaml` file do not already exist in the project, or else the template will fail
+- If a `catalog-info.yaml` file already exists in the repository, please use the built-in `Register Existing Component` button in the `Create...` page instead and provide the url to the `catalog-info.yaml`:
+  ![Built-in Register Existing Component](./images/built-in-register-existing-component.png)
+
+### Required Gitlab permissions
+
+- The Gitlab access token needs to have `api` read & write scopes and be added to your gitlab integration
+
+## Usage
+
+![gitlab-location-info-image](./images/gitlab-location-info.png)
+
+- `Gitlab hostname`: The hostname of your gitlab instance
+  - Default value: `gitlab.com`
+  - For public instances, use `gitlab.com`
+  - For Gitlab Enterprise instances, use the hostname of your instance. e.g. `gitlab.mycompany.com`
+  - **NOTE**: this hostname MUST exist in the gitlab integrations in the backstage instance's `app-config.yaml` with the correct access token
+- `Gitlab project owner`: The user, group or subgroup that the project is owned by
+  - Do not provide just the name of the group, you will need to provide the name in the url:
+    - Ex: A group may be named `mygroup` but the url could be `https://gitlab.com/mygroup2`, this template will need `mygroup2`
+  - For subgroups, use full slug for the subgroup. (`mygroup2/subgroup`, `mygroup2/subgroup/subsubgroup`, etc.)
+- `Gitlab project name`: The name of the project where your component is located
+
+![gitlab-component-info-image](./images/gitlab-component-info.png)
+
+- `Component Name` (Optional): The name used to identify the component in the backstage catalog
+  - **NOTE**: this name also must adhere to the backstage entity name format [requirements](https://github.com/backstage/backstage/blob/master/docs/architecture-decisions/adr002-default-catalog-file-format.md#name).
+  - Additionally, this name should not already be in use in the backstage catalog
+  - If left blank, the value of `Gitlab project name` will be used instead
+    - If the value of `Gitlab project name` is used, then it must also adhere to these requirements,
+  - If these requirements are not met, the component will not be ingested properly.
+  - Used to populate the [`metadata.name`](https://backstage.io/docs/features/software-catalog/descriptor-format/#specowner-required) field of the component's `catalog-info.yaml`
+- `Owner`: The owner of the component in the backstage catalog
+
+  - Expects a `User` or `Group` entity in the backstage catalog
+  - This value is inputted via a dropdown menu, and will only show users and groups that already exist in the backstage catalog
+  - This template will not function correctly if no `User` or `Group` entities exist in the backstage catalog
+  - Used to populate the [`spec.owner`](https://backstage.io/docs/features/software-catalog/descriptor-format/#specowner-required) field of the component's `catalog-info.yaml`
+
+- `Type`: The type of component in the backstage catalog
+  - Default value: `other`
+  - Well-known and common values: service, website, library.
+  - Used to populate the [`spec.type`](https://backstage.io/docs/features/software-catalog/descriptor-format#spectype-required) field of the component's `catalog-info.yaml`
+- `Lifecycle`: The lifecycle stage of the component in the backstage catalog
+  - Default value: `unknown`
+  - Well-known and common values include: experimental, production, deprecated.
+  - Used to populate the [`spec.lifecycle`](https://backstage.io/docs/features/software-catalog/descriptor-format/#speclifecycle-required) field of the component's `catalog-info.yaml`
+
+Once all these values are filled in, you should see a summary screen with all your inputted values.
+![gitlab-summary-image](./images/gitlab-summary.png)
+
+### Expected Output
+
+![gpt-result-image](./images/gpt-result.png)
+Once you press create, you should expect all the steps to be completed successfully and the component registered, but not ingested yet.
+
+To ingest the component, you will need to merge the merge request created by the template.
+To navigate to the merge request, click the `Go to Merge Request` button to be redirected to the corresponding merge request.
+Feel free to add any additional annotations to the `catalog-info.yaml` file before merging the merge request.
+Once the merge request is merged, wait up to 5 minutes for the component to be ingested into the catalog.
+
+Once ingested, navigate to the catalog (filter by `kind=Component`) and you should see your newly registered component.

templates/gitlab/register-gitlab-component/template.yaml

@@ -0,0 +1,109 @@
+apiVersion: scaffolder.backstage.io/v1beta3
+kind: Template
+metadata:
+  name: register-gitlab-component
+  title: Register existing component to Software Catalog from Gitlab
+  description: Registers existing component (Gitlab repository) to Software Catalog
+  tags:
+    - import
+    - catalog
+    - register
+spec:
+  owner: janus-authors
+  system: janus-idp
+  type: service
+
+  parameters:
+    - title: Provide information about the Gitlab location
+      required:
+        - gitlabHost
+        - projectOwner
+        - projectName
+      properties:
+        gitlabHost:
+          title: Gitlab hostname
+          type: string
+          description: Use gitlab.com or specify a hostname of your Gitlab Enterprise instance.
+          default: gitlab.com
+        projectOwner:
+          title: Gitlab project owner
+          type: string
+          description: "Can be a group, subgroup or a user. If using a subgroup, provide full ownership chain, ex: group/subgroup"
+        projectName:
+          title: Gitlab project name
+          type: string
+
+    - title: Provide information about the new component
+      required:
+        - componentOwner
+        - componentType
+        - componentLifecycle
+      properties:
+        componentName:
+          title: Component Name
+          type: string
+          description: Name of the created component. If left empty the name of the repository will be used.
+          # Refer to https://github.com/backstage/backstage/blob/master/docs/architecture-decisions/adr002-default-catalog-file-format.md#name
+          maxLength: 63
+          pattern: ^([A-Za-z0-9][-A-Za-z0-9_.]*)?[A-Za-z0-9]$
+        componentOwner:
+          title: Owner
+          description: Select an owner from the list or enter a reference to a Group or a User
+          type: string
+          ui:field: EntityPicker
+          ui:options:
+            catalogFilter:
+              kind:
+                - Group
+                - User
+        componentType:
+          title: Type
+          type: string
+          description: "The type of component. Well-known and common values: service, website, library."
+          default: other
+        componentLifecycle:
+          title: Lifecycle
+          type: string
+          description: "The lifecycle state of the component. Well-known and common values: experimental, production, deprecated."
+          default: unknown
+
+  steps:
+    - id: catalogTemplate
+      name: Create catalog-info.yaml file
+      action: fetch:template
+      input:
+        url: ../../../skeletons/catalog-info/
+        values:
+          componentName: ${{ parameters.componentName }}
+          orgName: ${{ parameters.projectOwner }}
+          sourceControl: gitlab.com
+          repoName: ${{ parameters.projectName }}
+          componentLifecycle: ${{ parameters.componentLifecycle }}
+          applicationType: ${{ parameters.componentType }}
+          owner: ${{ parameters.componentOwner }}
+    - id: publishMergeRequest
+      name: Open Merge Request with catalog-info.yaml
+      action: publish:gitlab:merge-request
+      input:
+        repoUrl: ${{ parameters.gitlabHost }}?repo=${{ parameters.projectName }}&owner=${{ parameters.projectOwner }}&
+        branchName: add-catalog-info
+        title: add catalog-info.yaml
+        description: |
+          This pull request adds a **Backstage entity metadata file** to this repository.
+
+          After this pull request is merged, the component will become available.
+
+          For more information, read an [overview of the Backstage software catalog](https://backstage.io/docs/features/software-catalog/).
+        removeSourceBranch: true
+    - id: register
+      name: Register component
+      action: catalog:register
+      input:
+        repoContentsUrl: https://${{ parameters.gitlabHost }}/${{ parameters.projectOwner }}/${{ parameters.projectName }}/${{ parameters.repositoryName }}-/blob/${{ steps.publishMergeRequest.output.targetBranchName }}/
+        catalogInfoPath: /catalog-info.yaml
+        optional: true
+
+  output:
+    links:
+      - title: "Go to Merge Request"
+        url: ${{ steps.publishMergeRequest.output.mergeRequestUrl }}