Use the add-new-prow-config.sh script to populate the $HOME/release/ci-operator/config/openshift/openshift-docs directory with a new Prow job branch configuration. The script uses the ./openshift-openshift-docs-BRANCH.yaml template file to create the new job config. After you create the job config, you run the CI make jobs to create the Prow jobs. Then, open a pull request against the https://github.com/openshift/release repository to make the Prow job live for that branch.

To add a new job to Prow CI, do the following:

1. Install Podman.

2. Fork and clone the https://github.com/openshift/release repository to $HOME/release.

   Note

   If you have already forked the repository, make sure it is up to date. Run the following commands: cd $HOME/release git remote add upstream [email protected]:openshift/release.git git checkout master git fetch upstream git rebase upstream/master git checkout <your_new_branch> (1) Replace <your_new_branch> with an appropriate branch name.

3. Create the new branch config by running the add-new-prow-config.sh script passing the $VERSION, $BRANCH and $DISTROS variables. Open a shell prompt in the openshift-docs/ directory, and run the script passing in the required variables, for example:

   ./scripts/prow/add-new-prow-config.sh 4.15 enterprise-4.15 "openshift-enterprise openshift-rosa openshift-rosa-hcp openshift-dedicated microshift"

   Note	Quote multiple distros to include them as a single item in the build config.

   The script copies the new job YAML to the ci-operator config folder in the $HOME/release directory.

   Important

   openshift-rosa, openshift-rosa-hcp, and openshift-osd distros should be included in main, current, and future enterprise branch builds only. When you add a new enterprise branch, remember to remove openshift-rosa, openshift-rosa-hcp, and openshift-osd distros from the most recent enterprise branch. For example, when the current version is 4.15, and you create a enterprise-4.16 branch, remove openshift-rosa and openshift-osd distros from the enterprise-4.15 branch build.

   Note	You can optionally add an openshift-docs-vale-review and openshift-docs-jira-links test step to the validate-asciidoc job. For more information, see openshift-docs test steps.

4. Change to the $HOME/release directory and verify that the new build config has been added.

   $HOME/release/ci-operator/config/openshift/openshift-docs/openshift-openshift-docs-enterprise-4.15.yaml

5. Run the following commands from the root of the $HOME/release repository to generate the rest of the Prow build configuration:

   make prow-config CONTAINER_ENGINE=podman WHAT=openshift/openshift-docs
   
   make CONTAINER_ENGINE=podman ci-operator-config WHAT=openshift/openshift-docs
   
   make jobs CONTAINER_ENGINE=podman WHAT=openshift/openshift-docs

   Ensure that the make build target succeeds.

6. Open a PR against the openshift/release master branch. Ensure that all Prow CI tests pass. Add a /pj-rehearse comment in the pull request to verify the new build.

7. Get an /lgtm approval from someone in the openshift-docs OWNERS file.

8. When you want to schedule the job for merge, add a /pj-rehearse ack comment to the pull request. The PR is merged automatically when all required approvals are provided and the PR passes all the required CI jobs. When the PR is merged, the job goes live on the relevant openshift-docs branch PRs.

   Note	Rebase often on the release branch when you open a pull request. The repository is very busy and the underlying infrastructure changes daily. Every time you rebase, rerun the CI make jobs.

For more information, see: Contributing CI configuration to the openshift/release repository