Custom release site

Introduction

You can create a custom release site, similar to the official ForgeOps release site, to publish and manage the image-tags used in ForgeOps deployments in your organization.

Using a custom release site, you can have better control over the image tags available to your teams and environments. You can use the site to publish only approved versions, maintain an internal mirror of release files, support controlled promotion between environments, or integrate release publication with your existing CI/CD and change-management processes.

If your custom release site follows the same pattern as the ForgeOps release site, you can use the forgeops tool to manage your custom Ping Advanced Identity Software product uptake and release cycles.

To use your custom release site with the forgeops tool, it must expose release metadata files for the platform components, such as AM, IDM, DS, PingGateway, and user-interface components. The files must use the names, structure, and format expected by the ForgeOps tooling that consumes them.

After you create and publish the site, configure your ForgeOps workflows to use its URL as the release source. This allows your deployments to retrieve release information from your custom release site instead of the public ForgeOps release site.

Before making a custom release site available for production use, verify that:

The site is reachable from the systems that run your ForgeOps commands and deployment pipelines.
The published files match the format expected by the ForgeOps tooling.
The site contains only product versions approved for your organization.
Changes to release files are reviewed, versioned, and auditable.
Access controls and HTTPS are configured according to your security requirements.

To enable the forgeops command to use your copy of releases.forgeops.com you need to set up a forgeops.conf file. If you don’t have a forgeops.conf file, copy the forgeops.conf.example file to your fork of the forgeops repository. Then update the following parameters in the forgeops.conf file:

Parameter	Sample value
The URL of your custom release site	https://releases.example.com
The URL of your base-image container registry	registry.example.com/images-base
The URL of your deployment-image container registry	registry.example.com/images

Parameter

Sample value

The URL of your custom release site

https://releases.example.com

The URL of your base-image container registry

registry.example.com/images-base

The URL of your deployment-image container registry

registry.example.com/images

Procedure to create a custom release site

Follow these steps to create and use your custom release site.

Obtain the release metadata files from the ForgeOps release site.

Use the files published on the official ForgeOps release site as a starting point for your custom release site. The official site index lists the JSON files separately for each platform component. Download the JSON files.

Keep the original file names unless you have a corresponding customization in the forgeops tooling. The RELEASES_SRC setting must point to the directory or site root that contains these files.
Select the releases and image tags.

Review each metadata file and remove the releases that you don’t want to use in your organization. For each release that you retain, update the tags list with the tags for the images in your container registries.

A release metadata file uses a releases map. The map groups patch releases under a major and minor version. Each patch release contains a tags list. For example:
```
{
  "releases": {
    "8.0": {
      "8.0.0": {
        "tags": ["8.0.0", "8.0.0-latest"]
      }
    }
  }
}
```
Use tags that exist in the registry configured for the corresponding component. Beginning custom tags with the ForgeOps x.y.z product version helps the forgeops info command identify the product version and helps you seek support for the specific product version. For example, if you have a custom tag for the 8.0.0 release of AM, use a tag such as 8.0.0-custom instead of custom-1.

If a release entry contains a scan value, retain or update it to reflect your scanning policy. The forgeops info command uses this value when it identifies supported releases.
Host the release metadata files.

Publish the customized JSON files at a stable HTTP or HTTPS location. The files must be reachable from the systems that run the forgeops tool and from any build or deployment automation that uses the release site.

For example, if you publish the files at https://releases.example.com, the idm.json file should be available at:
```
https://releases.example.com/idm.json
```
Confirm that each file is accessible and returns valid JSON before configuring the forgeops repository. Protect the site with HTTPS and apply any access controls required by your organization.
Set up your ForgeOps repository.

Change to the directory that contains your fork or working copy of the forgeops repository. The commands in this procedure modify files in this repository and commit the configuration so that your team and automation can use the same settings.
```
$ cd /path/to/forgeops
```
Create the configuration file.

Copy the example configuration file before adding your custom release and registry settings. The example file provides the expected configuration format and preserves the default settings that you don’t need to change.

If forgeops.conf already exists, don’t overwrite it. Instead, open the file and update the existing RELEASES_SRC, BASE_REPO, and DEPLOY_REPO settings as described in the next step.
```
$ cp forgeops.conf.example forgeops.conf
```
Configure the release site and container registries.

Add the following settings to the new forgeops.conf:
```
RELEASES_SRC=https://releases.example.com
BASE_REPO=registry.example.com/images-base
DEPLOY_REPO=registry.example.com/images
```
The forgeops tool reads these settings when it selects product images. Make sure that the registries are accessible to the users, build systems, and deployment pipelines that run your ForgeOps commands. Configure registry authentication separately. Don’t store registry credentials in forgeops.conf.
Verify the custom release source.

Before committing the configuration, use the forgeops info command to confirm that the tool can read the releases published on your custom site.
```
$ forgeops info --list-releases
```
The command should list the releases available from https://releases.example.com. If the command fails, verify the following:
- RELEASES_SRC points to the root of the custom release site.
- The release metadata files are available at the expected paths.
- The host running the command can resolve and reach the site.
- The release files are valid and use the expected JSON structure.
Review and commit the configuration.

Review the configuration changes before committing them. Confirm that the release site and registry URLs are correct and that the file doesn’t contain credentials or other sensitive information.
```
$ git diff — forgeops.conf
$ git diff --check
$ git add forgeops.conf
$ git commit -m 'Configure custom release site and registries'
```
Push the configuration to your repository.

Push the commit to the branch used by your team or automation. This makes the custom release settings available wherever the repository is cloned or updated.
```
$ git push
```
Use the custom release site.

After the configuration is available in your working copy, use the forgeops image command to select a release. For example:
```
$ forgeops image --release platform-release platform
```
The command uses RELEASES_SRC to find the component image tags and uses BASE_REPO and DEPLOY_REPO instead of ForgeOps registries. It then updates the applicable ForgeOps image-selection files for the selected release.

Commit the generated image-selection files so that other team members and environments use the same component versions. When you promote or update a release, repeat the image-selection process and review the resulting changes before committing them.