Skip to content

Commit f4d6479

Browse files
openshift-cherrypick-robotGitHub Actions
openshift-cherrypick-robot
and
GitHub Actions
authored
[release-1.8] RHIDP-8632: Update the Bulk Import Plugin to Integrate with Existing Backstage Templates and Orchestrator Workflows (#1457)
* Bulk import * Bulk Import plugin * Bulk Import plugin * Update bulk import * Update bulk import * Update bulk import * Update bulk import * Add a new module * Apply suggestions * Apply suggestions * Apply peers suggestions * Apply new suggestion * Apply suggestions * Update suggestions * Update suggestions * Apply suggestions * Apply suggestions * Apply suggestions * Apply suggestions --------- Co-authored-by: GitHub Actions <github-actions@github.com>
1 parent 6c9096b commit f4d6479

File tree

4 files changed

+133
-0
lines changed

4 files changed

+133
-0
lines changed

‎assemblies/assembly-bulk-importing-from-github.adoc‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -15,3 +15,8 @@ include::modules/importing-repositories/procedure-managing-the-imported-reposito
1515

1616
include::modules/importing-repositories/procedure-understanding-bulk-import-audit-logs.adoc[leveloffset=+1]
1717

18+
include::modules/importing-repositories/concept-bulk-import-scaffolder-template.adoc[leveloffset=+1]
19+
20+
include::modules/importing-repositories/procedure-integrating-bulk-import-with-orchestrator-workflows.adoc[leveloffset=+1]
21+
22+
include::modules/importing-repositories/concept-data-handoff-and-custom-workflow-design.adoc[leveloffset=+1]

‎modules/importing-repositories/concept-bulk-import-scaffolder-template.adoc‎

Lines changed: 58 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,58 @@
1+
:_mod-docs-content-type: CONCEPT
2+
3+
[id="bulk-import-scaffolder-template"]
4+
= Input parameters for Bulk Import Scaffolder template
5+
6+
As an administrator, you can use the Bulk Import plugin to run a Scaffolder template task with specified parameters, which you must define within the template.
7+
8+
The Bulk Import plugin analyzes Git repository information and provides the following parameters for the Scaffolder template task:
9+
10+
`repoUrl`:: Normalized repository URL in the following format:
11+
+
12+
[source,yaml]
13+
----
14+
${gitProviderHost}?owner=${owner}&repo=${repository-name}
15+
----
16+
17+
`name`:: The repository name.
18+
19+
`organization`:: The repository owner, which can be a user nickname or organization name.
20+
21+
`branchName`:: The proposed repository branch. By default, the proposed repository branch is `bulk-import-catalog-entity`.
22+
23+
`targetBranchName`:: The default branch of the Git repository.
24+
25+
`gitProviderHost`:: The Git provider host parsed from the repository URL. You can use this parameter to write `Git-provider-agnostic` templates.
26+
27+
Example of a Scaffolder template:
28+
[source,yaml]
29+
----
30+
parameters:
31+
- title: Repository details
32+
required:
33+
- repoUrl
34+
- branchName
35+
- targetBranchName
36+
- name
37+
- organization
38+
properties:
39+
repoUrl:
40+
type: string
41+
title: Repository URL (Backstage format)
42+
description: github.com?owner=Org&repo=repoName
43+
organization:
44+
type: string
45+
title: Owner of the repository
46+
name:
47+
type: string
48+
title: Name of the repository
49+
branchName:
50+
type: string
51+
title: Branch to add the catalog entity to
52+
targetBranchName:
53+
type: string
54+
title: Branch to target the PR/MR to
55+
gitProviderHost:
56+
type: string
57+
title: Git provider host
58+
----

‎modules/importing-repositories/concept-data-handoff-and-custom-workflow-design.adoc‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
:_mod-docs-content-type: CONCEPT
2+
3+
[id="full-data-handoff-and-custom-workflow-design"]
4+
5+
= Data handoff and custom workflow design
6+
7+
When you configure the Bulk Import plugin by setting the importAPI field to `scaffolder`, the Bulk Import Backend passes all necessary context directly to the Scaffolder API.
8+
9+
As an administrator, you can define the Scaffolder template workflow and structure the workflow to do the following:
10+
11+
Define template parameters to consume input:: Structure the Scaffolder template to receive the repository data as template parameters for the current workflow run. The template must be generic, and not specific to a single repository, so that it can successfully run for every repository in the bulk list.
12+
13+
Automate processing for each repository:: Implement the custom logic needed for a single repository within the template. The Orchestrator iterates through the repository list, launching the template once for each repository and passes only the data for that single repository to the template run. This allows you to automate tasks such as creating the `catalog-info.yaml`, running compliance checks, or registering the entity with the catalog.

‎modules/importing-repositories/procedure-integrating-bulk-import-with-orchestrator-workflows.adoc‎

Lines changed: 57 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,57 @@
1+
:_mod-docs-content-type: PROCEDURE
2+
3+
[id="integrating-bulk-import-with-orchestrator-workflows"]
4+
= Setting up a custom Scaffolder workflow for Bulk Import
5+
6+
As an administrator, you can create a custom Scaffolder template in line with the repository conventions of your organization and add the template into the {product} catalog for use by the Bulk Import plugin on multiple selected repositories.
7+
8+
You can define various custom tasks, including, but not limited to the following:
9+
10+
* Importing existing catalog entities from a repository
11+
* Creating pull requests for cleanup
12+
* Calling webhooks for external system integration
13+
14+
.Prerequisites
15+
16+
* You created a custom Scaffolder template for the Bulk Import plugin.
17+
18+
* You have run your {product-very-short} instance with the following environment variable enabled to allow the use of the Scaffolder functionality:
19+
+
20+
[source,yaml]
21+
----
22+
export NODE_OPTIONS=--no-node-snapshot
23+
----
24+
25+
.Procedure
26+
27+
* Configure your {my-app-config-file} configuration to instruct the Bulk Import plugin to use your custom template as shown in the following example:
28+
+
29+
[source,yaml]
30+
----
31+
bulkImport:
32+
importTemplate: <your_template_entity_reference_or_template_name>
33+
importAPI: `open-pull-requests` | `scaffolder`;
34+
----
35+
+
36+
where:
37+
38+
`importTemplate:`::
39+
Enter your Scaffolder template entity reference.
40+
41+
`importAPI`::
42+
Set the API to 'scaffolder' to trigger the defined workflow for high-fidelity automation. This field defines the import workflow and currently supports two following options:
43+
44+
`open-pull-requests`:: This is the default import workflow, which includes the logic for creating pull requests for every selected repository.
45+
46+
`scaffolder`:: This workflow uses an import scenario defined in the Scaffolder template to create import jobs. Select this option to use the custom import scenario defined in your Scaffolder template.
47+
+
48+
Optional: You can direct the Bulk Import plugin to hand off the entire list of selected repositories to a custom Orchestrator workflow.
49+
+
50+
[IMPORTANT]
51+
====
52+
The Scaffolder template must be generic and not specific to a single repository if you want your custom Scaffolder template to run successfully for every repository in the bulk list.
53+
====
54+
55+
.Verification
56+
57+
* The Bulk Import plugin runs the custom Scaffolder template for the list of repositories using the `/task-imports` API endpoint.

0 commit comments

Comments
 (0)