Chapter 4. Integrating products and external services

1. Create a GitHub personal access token.
2. Create a GitHub application.

Procedure

1. Go to your Developer settings page on GitHub.
2. In the left navigation panel, under Personal access tokens, click Tokens (classic).
3. From the Generate new token drop-down menu, select Generate new token (classic). Authenticate if prompted.
4. Enter a name, select an expiration date, and under Select scopes, select repo. This automatically includes all scopes from repo:status to security_events.
5. Click Generate token. GitHub redirects you to a new page where your token is displayed.
6. (Optional) Save the token to a file, such as values.txt, for reuse in later steps.

Procedure

1. Run the following command to create the GitHub application:

   bash-5.1$ tssc integration github-app \
     --create \
     --token="$GH_TOKEN" \
     --org="$GH_ORG_NAME" \
     $GH_APP_NAME

   Replace the following variables:

   • $GH_TOKEN: The GitHub personal access token
   • $GH_ORG_NAME: The GitHub organization name
   • $GH_APP_NAME: The name of the GitHub application
2. Copy the URL from the command output and open it in a browser.
3. Click Create your GitHub App.
4. If prompted, authenticate to GitHub.
5. Click Create GitHub App for <your organization>.
6. When the application is created, click the link in the success message to install the application in your GitHub organization.
7. On the redirected GitHub page, click Install.
8. Select the GitHub organization that you are using for RHADS - SSC.

9. When prompted, select All repositories, and click Install.

   Note

   You may want to keep this GitHub page open. The banner includes a link (beginning with https://backstage-developer-hub-rhtap…​) to access RHADS - SSC after installation.

Procedure

1. Before you integrate RHACS, obtain an API token and the Central endpoint URL. The URL must include the protocol, hostname, and port. For example, https://central-rhacs.example.com:443.

   1. Follow the instructions at Create an RHACS API token to generate the token.
   2. Save the token to a file, such as values.txt, for reuse in later steps.
   3. Follow the instructions at Configure the Central endpoint URL to locate your ACS Central endpoint.
   4. Save the endpoint URL to a file, such as values.txt, for reuse in later steps.

2. In your tssc container, run the following integration command:

   bash-5.1$ tssc integration acs \
     --endpoint="$ACS_ENDPOINT" \
     --token="$ACS_TOKEN"

   Replace the following variables:

   • $ACS_ENDPOINT: The URL of your RHACS Central endpoint
   • $ACS_TOKEN: The RHACS API token

Procedure

1. In a web browser, log in to your Quay account.

   1. Browse to your organization’s robot accounts.
   2. Select an appropriate robot account. For example, a robot account with write permission.
   3. In the popup, select Docker Configuration > View [username-robotaccount]-auth.json.
   4. Copy the string value (without quotation marks) that follows "auth":.
   5. Save the auth value and your Quay username to a file, such as values.txt, so that you can use them when constructing the Docker configuration.
   6. Repeat the steps 1b through 1e for the robot account with read permission.
2. In a separate browser tab, go to the Repositories page.
3. Under Users and Organizations, click the name of the organization you want to use with RHADS - SSC.
4. In the left-hand navigation, click Applications.
5. Click Create New Application and enter a name.
6. Click the name of the application that you created.
7. In the left-hand navigation, click Generate Token.
8. In the permissions list, select View all visible repositories.
9. Click Generate Access Token.
10. Click Authorize Application. Quay displays the access token. Copy this token.

1. In your tssc container, run the following command to integrate Quay with RHADS - SSC, passing all required values inline:

   # Docker configuration JSON string for the read/write robot account
   bash-5.1$ tssc integration quay \
     --dockerconfigjson='{"auths":{"quay.io":{"auth":"<auth_token_write_permission>","email":""}}}' \
     --dockerconfigjsonreadonly='{"auths":{"quay.io":{"auth":"<auth_token_read_permission>","email":""}}}'
     --token="<quay_access_token>" \
     --url="https://quay.io"

   Replace the following values:

   • <auth_token_write_permission>: The value from the auth.json file under "auth": for read and write robot account.
   • <auth_token_read_permission>: The value from the auth.json file under "auth": for read only robot account.
   • <quay_access_token>: The access token you generated via the OAuth application
   • https://quay.io: The Quay instance URL (use your custom URL if self-hosted)

Procedure

1. In the tssc container, run the following integration command:

   bash-5.1$ tssc integration bitbucket \
     --username="$BB_USERNAME" \
     --app-password="$BB_TOKEN" \
     --host="$BB_URL"

   Replace the following variables:

   • $BB_USERNAME: Your Bitbucket username
   • $BB_TOKEN: Your Bitbucket app password

   • $BB_URL: Your Bitbucket host URL (optional)

     Note

     If you are using the default Bitbucket Cloud host (bitbucket.org), you can omit the --host option.

Procedure

1. In the tssc container, run the following integration command:

   bash-5.1$ tssc integration gitlab \
     --token="$GL_API_TOKEN" \
     --host="$GL_URL" \
     --group="$GL_GROUP"

   Replace the following variables:

   • $GL_API_TOKEN: Your GitLab personal access token
   • $GL_URL: Your GitLab host URL (omit this option if using gitlab.com)
   • $GL_GROUP: The GitLab group name that contains your repositories

Procedure

1. In the tssc container, run the following integration command:

   bash-5.1$ tssc integration jenkins \
     --token="$JK_API_TOKEN" \
     --url="$JK_URL" \
     --username="$JK_USERNAME"

   Replace the following variables:

   • $JK_API_TOKEN: Your Jenkins API token
   • $JK_URL: The URL of your Jenkins instance
   • $JK_USERNAME: Your Jenkins user ID

Procedure

1. In the tssc container, run the following integration command:

   bash-5.1$ tssc integration azure \
     --organization="$AZURE_ORGANIZATION" \
     --host="$AZURE_HOST_URL" \
     --token="$AZURE_API_TOKEN" \
     --tenantID="$AZURE_TENANT_ID" \
     --client-id="$AZURE_CLIENT_ID" \
     --client-secret="$AZURE_CLIENT_SECRET"

   Replace the following variables:

   • $AZURE_ORGANIZATION: Your Azure DevOps organization name
   • $AZURE_HOST_URL: Your DevOps base URL (omit this option if using the default dev.azure.com)
   • $AZURE_API_TOKEN: Your personal access token
   • $AZURE_TENANT_ID: (Optional) The AAD tenant ID
   • $AZURE_CLIENT_ID: (Optional) The AAD application client ID
   • $AZURE_CLIENT_SECRET: (Optional) The AAD application client secret

Procedure

1. In the Artifactory web UI, go to the Administration view.
2. Click the green Set Up Client/CI Tool button next to the repository that you want to use.
3. Select Docker Client.

4. Follow the instructions in the UI to authenticate from your CLI:

   1. The UI generates a token that is used as your Docker password. Save the token to a file, such as values.txt, for reuse in later steps

   2. After logging in to JFrog via the CLI, you should see a message that your password was saved in a file such as ~/.docker/config.json.

      Note

      If you do not see this message, you can manually generate the config.json content in a later step.

5. In your tssc container, run the following integration command:

   bash-5.1$ tssc integration artifactory \
     --url="$AF_URL" \
     --dockerconfigjson='$AF_DOCKERCONFIGJSON' \
     --token="$AF_API_TOKEN"

   Replace the following variables:

   • $AF_URL: The URL of your JFrog instance (for example, https://myusername.jfrog.io)
   • $AF_DOCKERCONFIGJSON: The contents of the config.json file where the password was stored

   • $AF_API_TOKEN: The token generated by JFrog

     Note

     Make sure to wrap the $AF_DOCKERCONFIGJSON value in single quotes to preserve the JSON structure.

     If the CLI did not generate the config.json file, you can manually create its contents using the following format:

     {
       "auths": {
         "<URL for your JFrog instance>": {
           "auth": "<base64 format of username:password>",
           "email": ""
         }
       }
     }

Procedure

1. (Optional) Create temporary environment variables and store the following values:

   REGISTRY_URL="<url to the nexus container registry>"
   AUTHFILE='auth.json'  # This file will be created in the next step.

   If you choose not to create these variables, remember to replace the variables in the code examples with relevant values.

2. Log in to your Nexus container registry using Podman and generate a Docker-compatible authentication file:

   podman login --authfile="${AUTHFILE}" "${REGISTRY_URL}"

   This command logs in to Nexus, creates an auth.json file, and stores your Nexus username and password in it.

3. In your tssc container, run the following integration command:

   tssc integration nexus \
     --url="${REGISTRY_URL}" \
     --dockerconfigjson="$(cat ${AUTHFILE})"

4. Remove the local auth.json file as it is no longer needed.

   rm "${AUTHFILE}"