Red Hat Summit Red Hat SummitSupportConsoleDevelopersStart a trialContact

Authentication

builds for Red Hat OpenShift 1.7

Understanding authentication at runtime

Red Hat OpenShift Documentation Team

Abstract

This document provides information about authentication at runtime.

Developers building images may need to configure authentication and use secrets to handle sensitive data safely within the build process. Access to build resources is governed by role-based access control (RBAC), defined by cluster administrators to ensure only authorized users can act securely.

1.1. Build secret annotation
Copy link

Add an annotation to a build secret to ensure the build controller reconciles on create, update, or delete events for the referenced build secret.

The following example shows the usage of an annotation with a secret: 

apiVersion: v1
data:
  .dockerconfigjson: <pull_secret>
kind: Secret
metadata:
  annotations:
    build.shipwright.io/referenced.secret: "true"
  name: secret-docker
type: kubernetes.io/dockerconfigjson
Copy to Clipboard Toggle word wrap

where:

<pull_secret>
Specifies the Base64-encoded pull secret used by the build.
build.shipwright.io/referenced.secret
Specifies the value of the build.shipwright.io/referenced.secret annotation.

This annotation ensures the controller ignores secret events unless the secret is explicitly referenced by a build. For example, if a secret does not include this annotation, the build controller will not reconcile when that secret changes, even if an event is triggered. Reconciling on relevant events allows the build controller to re-run build configuration validations, helping detect missing or misconfigured dependencies early.

1.2. Authentication to Git repositories
Copy link

You can define the following types of authentication for a Git repository:

  • Basic authentication
  • Secure Shell (SSH) authentication

You can configure a Git secret with these authentication methods.

1.2.1. Basic authentication
Copy link

Configure basic authentication credentials for a Git repository by creating a Kubernetes secret with a username and password. The following example shows a Git basic-auth secret referenced by a build: 

apiVersion: v1
kind: Secret
metadata:
  name: secret-git-basic-auth
  annotations:
    build.shipwright.io/referenced.secret: "true"
type: kubernetes.io/basic-auth
stringData:
  username: <plaintext_username>
  password: <plaintext_password>
Copy to Clipboard Toggle word wrap

where:

type
Specifies the Kubernetes secret type. kubernetes.io/basic-auth indicates that the secret contains credentials for basic authentication.
stringData
Specifies the username and password used for basic authentication to the Git repository referenced by the build.

1.2.2. SSH authentication
Copy link

With Secure Shell (SSH) authentication, configure Tekton annotations to specify the hostname of the Git repository provider. For example, use github.com for GitHub or gitlab.com for GitLab.

The following example shows a Kubernetes secret configured for SSH authentication to a Git repository: 

apiVersion: v1
kind: Secret
metadata:
  name: secret-git-ssh-auth
  annotations:
    build.shipwright.io/referenced.secret: "true"
type: kubernetes.io/ssh-auth
data:
  ssh-privatekey: |
    LS0tLS1CRUdJTiBPUEVOU1NIIFBSSVZBVEUgS0VZLS0tLS0K
    ZmFrZS1zc2gta2V5LWZvci1kb2NzLW9ubHkK
    LS0tLS1FTkQgT1BFTlNTSCBQUklWQVRFIEtFWS0tLS0t
Copy to Clipboard Toggle word wrap

where:

type
Specifies the Kubernetes secret type. kubernetes.io/ssh-auth indicates that the secret contains SSH credentials.
ssh-privatekey
Specifies the Base64-encoded SSH private key used to authenticate to the Git repository. You can generate this value by running base64 ~/.ssh/id_rsa, where ~/.ssh/id_rsa is the default location of the SSH private key commonly used for Git authentication.

1.2.3. Usage of Git secret
Copy link

After creating a secret in the relevant namespace, you can reference it in your Build custom resource (CR). You can configure the Git secret to use either basic authentication or Secure Shell (SSH) authentication.

The following example shows the usage of a Git secret with SSH authentication type: 

apiVersion: shipwright.io/v1beta1
kind: Build
metadata:
  name: buildah-golang-build
spec:
  source:
    git:
      url: git@gitlab.com:userjohn/newtaxi.git
      cloneSecret: secret-git-ssh-auth
Copy to Clipboard Toggle word wrap

The following example shows the usage of a Git secret with basic authentication type: 

apiVersion: shipwright.io/v1beta1
kind: Build
metadata:
  name: buildah-golang-build
spec:
  source:
    git:
      url: https://gitlab.com/userjohn/newtaxi.git
      cloneSecret: secret-git-basic-auth
Copy to Clipboard Toggle word wrap

1.3. Authentication to container registries
Copy link

To push images to a private container registry, you must create a secret in the relevant namespace and then reference it in your Build custom resource (CR).

Prerequisites

  • You have installed the Builds for Red Hat OpenShift Operator on the OpenShift Container Platform cluster.
  • You have installed the oc CLI.

Procedure

  1. Run the following command to generate a secret object: 

    $ oc --namespace <namespace> create secret docker-registry <container_registry_secret_name> \
  --docker-server=<registry_host> \
  --docker-username=<username> \
  --docker-password=<password> \
  --docker-email=<email_address>
    Copy to Clipboard Toggle word wrap

    where:

    <namespace>
    Specifies the namespace where you want to create the secret.
    <container_registry_secret_name>
    Specifies the name of the Secret resource that stores the container registry credentials.
    <registry_host>
    Specifies the registry URL in the format https://<registry_server>/<registry_host>.
    <username>
    Specifies the registry username.
    <password>
    Specifies the password or an access token for the container registry.
    <email_address>
    Specifies the email address associated with the container registry credentials.

  2. Run the following command to annotate the secret: 

    $ oc --namespace <namespace> annotate secrets <container_registry_secret_name> build.shipwright.io/referenced.secret='true'
    Copy to Clipboard Toggle word wrap

    where:

    <namespace>
    Specifies the namespace in which you want to create the secret.
    <container_registry_secret_name>
    Specifies the name of the Secret resource that stores the container registry credentials.

  3. Set the value of the spec.output.pushSecret field to the secret name in your Build CR: 

    apiVersion: shipwright.io/v1beta1
kind: Build
metadata:
  name: buildah-golang-build
  # ...
  output:
    image: <path_to_image>
    pushSecret: <container_registry_secret_name>
    Copy to Clipboard Toggle word wrap

    where

    <path_to_image>
    Specifies the location of the output image.
    <container_registry_secret_name>
    Specifies the name of the Secret resource that stores the container registry credentials.
  4. Run a build using the Build CR. The container registry credentials are verified during the image push. If authentication fails, the build does not push the image.

1.4. Role-based access control
Copy link

By default, builds for Red Hat OpenShift installation includes the following two cluster-wide roles for using Builds objects:

  • shpwright-build-aggregate-view: Grants read access to the Builds resources, such as BuildStrategy, ClusterBuildStrategy, Build, and BuildRun. This role is aggregated into the Kubernetes view role.
  • shipwright-build-aggregate-edit: Grants write access to the Builds resources that are configured at namespace level. The build resources include BuildStrategy, Build, and BuildRun. Read access is granted to all ClusterBuildStrategy resources. This role is aggregated into the Kubernetes edit and admin roles.

Only cluster administrators have write access to the ClusterBuildStrategy resources by default. You can change this setting by creating a separate Kubernetes ClusterRole with the desired permissions and binding it to the appropriate users.

Legal Notice
Copy link

Copyright © Red Hat

OpenShift documentation is licensed under the Apache License 2.0 (https://www.apache.org/licenses/LICENSE-2.0).

Modified versions must remove all Red Hat trademarks.

Portions adapted from https://github.com/kubernetes-incubator/service-catalog/ with modifications by Red Hat.

Red Hat, Red Hat Enterprise Linux, the Red Hat logo, the Shadowman logo, JBoss, OpenShift, Fedora, the Infinity logo, and RHCE are trademarks of Red Hat, Inc., registered in the United States and other countries.

Linux® is the registered trademark of Linus Torvalds in the United States and other countries.

Java® is a registered trademark of Oracle and/or its affiliates.

XFS® is a trademark of Silicon Graphics International Corp. or its subsidiaries in the United States and/or other countries.

MySQL® is a registered trademark of MySQL AB in the United States, the European Union and other countries.

Node.js® is an official trademark of the OpenJS Foundation.

The OpenStack® Word Mark and OpenStack logo are either registered trademarks/service marks or trademarks/service marks of the OpenStack Foundation, in the United States and other countries and are used with the OpenStack Foundation’s permission. We are not affiliated with, endorsed or sponsored by the OpenStack Foundation, or the OpenStack community.

All other trademarks are the property of their respective owners.

Red Hat logoGithubredditYoutubeTwitter

Learn

Try, buy, & sell

Communities

About Red Hat Documentation

We help Red Hat users innovate and achieve their goals with our products and services with content they can trust. Explore our recent updates.

Making open source more inclusive

Red Hat is committed to replacing problematic language in our code, documentation, and web properties. For more details, see the Red Hat Blog.

About Red Hat

We deliver hardened solutions that make it easier for enterprises to work across platforms and environments, from the core datacenter to the network edge.

Theme

© 2026 Red HatBack to top