diff --git a/templates/github/register-component/README.md b/templates/github/register-component/README.md deleted file mode 100644 index cef61c21..00000000 --- a/templates/github/register-component/README.md +++ /dev/null @@ -1,14 +0,0 @@ -# Register existing component to Service Catalog - -This template is intended to be used as a starting point for registering an existing repository to the Service Catalog. - -Currently, it only supports repositories hosted on GitHub (both github.com and GitHub Enterprise are supported). - -## 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. \ No newline at end of file diff --git a/templates/github/register-github-component/README.md b/templates/github/register-github-component/README.md new file mode 100644 index 00000000..4125f2c6 --- /dev/null +++ b/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: + github: + - host: github.mycompany.com # this must match the hostname of your Github 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 create new branches and push files. + - **Pull requests**: **_Read & write_** - To create pull requests. + - **Commit statuses**: **_Read-only_** - 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. diff --git a/templates/github/register-github-component/images/github-component-info.png b/templates/github/register-github-component/images/github-component-info.png new file mode 100644 index 00000000..761a747f Binary files /dev/null and b/templates/github/register-github-component/images/github-component-info.png differ diff --git a/templates/github/register-github-component/images/github-location-info.png b/templates/github/register-github-component/images/github-location-info.png new file mode 100644 index 00000000..d57704bd Binary files /dev/null and b/templates/github/register-github-component/images/github-location-info.png differ diff --git a/templates/github/register-github-component/images/github-summary.png b/templates/github/register-github-component/images/github-summary.png new file mode 100644 index 00000000..d422d068 Binary files /dev/null and b/templates/github/register-github-component/images/github-summary.png differ diff --git a/templates/github/register-github-component/images/gpt-result.png b/templates/github/register-github-component/images/gpt-result.png new file mode 100644 index 00000000..b1ec0d0e Binary files /dev/null and b/templates/github/register-github-component/images/gpt-result.png differ diff --git a/templates/github/register-component/template.yaml b/templates/github/register-github-component/template.yaml similarity index 81% rename from templates/github/register-component/template.yaml rename to templates/github/register-github-component/template.yaml index 6b591544..037220b0 100644 --- a/templates/github/register-component/template.yaml +++ b/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 @@ -21,7 +21,7 @@ spec: - repositoryName properties: githubHost: - title: GitHub hostname + title: GitHub Hostname type: string description: Use github.com for GitHub Free, Pro, & Team or specify a hostname of your GitHub Enterprise instance. default: github.com @@ -29,7 +29,7 @@ spec: title: GitHub Organization type: string repositoryName: - title: Repository name + title: Repository Name type: string - title: Provide information about the new component @@ -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: @@ -99,7 +102,7 @@ spec: For more information, read an [overview of the Backstage software catalog](https://backstage.io/docs/features/software-catalog/). - id: register - name: Register component + name: Register Component action: catalog:register input: repoContentsUrl: https://${{ parameters.githubHost }}/${{ parameters.githubOrganization }}/${{ parameters.repositoryName }}/blob/${{ steps.publishPR.output.targetBranchName }}/ @@ -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 }} diff --git a/templates/gitlab/register-gitlab-component/README.md b/templates/gitlab/register-gitlab-component/README.md new file mode 100644 index 00000000..cf99714a --- /dev/null +++ b/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. diff --git a/templates/gitlab/register-gitlab-component/images/built-in-register-existing-component.png b/templates/gitlab/register-gitlab-component/images/built-in-register-existing-component.png new file mode 100644 index 00000000..8b7decf9 Binary files /dev/null and b/templates/gitlab/register-gitlab-component/images/built-in-register-existing-component.png differ diff --git a/templates/gitlab/register-gitlab-component/images/gitlab-component-info.png b/templates/gitlab/register-gitlab-component/images/gitlab-component-info.png new file mode 100644 index 00000000..860468fc Binary files /dev/null and b/templates/gitlab/register-gitlab-component/images/gitlab-component-info.png differ diff --git a/templates/gitlab/register-gitlab-component/images/gitlab-location-info.png b/templates/gitlab/register-gitlab-component/images/gitlab-location-info.png new file mode 100644 index 00000000..2521ae92 Binary files /dev/null and b/templates/gitlab/register-gitlab-component/images/gitlab-location-info.png differ diff --git a/templates/gitlab/register-gitlab-component/images/gitlab-summary.png b/templates/gitlab/register-gitlab-component/images/gitlab-summary.png new file mode 100644 index 00000000..ce7137a9 Binary files /dev/null and b/templates/gitlab/register-gitlab-component/images/gitlab-summary.png differ diff --git a/templates/gitlab/register-gitlab-component/images/gpt-result.png b/templates/gitlab/register-gitlab-component/images/gpt-result.png new file mode 100644 index 00000000..086384cb Binary files /dev/null and b/templates/gitlab/register-gitlab-component/images/gpt-result.png differ diff --git a/templates/gitlab/register-gitlab-component/template.yaml b/templates/gitlab/register-gitlab-component/template.yaml new file mode 100644 index 00000000..5d101a59 --- /dev/null +++ b/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 }}