Configuring CloudBees Previews for the first time

Prerequisites

CloudBees Previews Helm chart, installed as per the installation instructions
Admin access to the installation cluster
A CI pipeline that builds the preview image

Configuration

After installing CloudBees Previews, you must configure your Git repositories. Complete the following steps for each repository.

The examples use GitHub as the SCM provider, but CloudBees Previews supports a variety of other providers as well.

Creating the personal access token

CloudBees Previews needs to be able to clone your Git repository and to post comments on pull requests. In the case of GitHub, CloudBees Previews can optionally create deployments.

To make the necessary API calls, CloudBees Previews requires a personal access token (PAT). For GitHub, the steps to create a personal access token are documented in Creating a personal access token. Choose the repo scope.

CloudBees recommends that you create a so-called bot or machine user account and use its PAT. This bot needs to have access to each of the configured repositories. For GitHub, the steps to give a user access to a repository are documented in Managing teams and people with access to your repository.

The minimal required role when adding a user to a repository is the Read role. The Read role allows CloudBees Previews to clone the repository and post pull request comments. If you want preview links to be displayed as GitHub Deployments, you must choose the Write role.

Creating the Kubernetes Secret

Once you have your PAT, you must store it in a Kubernetes Secret:

Example Kubernetes Secret holding the SCM API token.

apiVersion: v1
kind: Secret
metadata:
  name: acme-github-token  (1)
stringData:
  user: <user>             (2)
  token: <token>           (3)▼

1	Name of the secret. This value is mandatory.
2	The username for whom the token was generated. This value is mandatory.
3	The token value. This value is mandatory.

You can use kubectl to create the secret, for example:

Creating Kubernetes Secret for SCM API token

kubectl --namespace previews create secret generic acme-github-token --from-literal=user='<user>' --from-literal=token='<token>'▼

Creating the GitRepository Custom Resources

Once you have created your secret containing the Git API token, you reference it in a GitRepository Custom Resource (CR). For each repository, create a GitRepository CR using kubectl:

GitRepository CR without webhook secret.

kubectl create -f - <<EOF
apiVersion: environment.cloudbees.com/v1alpha1
kind: GitRepository
metadata:
  name: acme-web                             (1)
  namespace: previews
spec:
  url: https://github.com/acme/acme-web.git  (2)
  apiTokenSecretRef:
    name: acme-github-token                  (3)
EOF▼

1	Name for the resource. This value is mandatory.
2	HTTPS Git clone URL for the repository. This value is mandatory.
3	Name of the secret containing the Git API token for the referenced Git repository. This value is mandatory.

CloudBees Previews only supports HTTPS Git URLs.

For a full reference, see GitRepository CR.

Registering the webhook

When a user creates a pull request or requests a preview environment, CloudBees Previews is notified via webhooks. You must configure a webhook for each source repository. The webhook configuration is specific to your SCM provider. Refer to your SCM provider’s documentation for more information about creating webhooks. Creating webhooks describes how to create a webhook on GitHub, for example.

The webhook URL differs depending on the chosen installation options. In the case of Basic installation via Helm, the payload URL is http://webhook.previews.acme.com. You can verify the Ingress URL by running:

Determining the configured Ingress URL of the CloudBees Preview webhook component

$ kubectl --namespace=previews get ingress webhook
NAME      CLASS    HOSTS                              ADDRESS     PORTS     AGE
webhook   <none>   webhook.previews.acme.com          localhost   80, 443   34m▼

The webhook’s content type must be application/json.

Refer to Securing your webhooks for more information on how to further secure your SCM provider integration.

Adding the .preview.yaml configuration file

Once CloudBees Previews is installed and configured, you can configure your application source. CloudBees Previews is declarative, and you must add a .preview.yaml configuration file to each preview-enabled repository.

CloudBees Previews supports several deployment technologies. In this example, we are using its ability to generate Kubernetes resources. Refer to the Generated manifests section of the .preview.yaml documentation for a more detailed description of the available configuration options.

Assuming your application is already containerized, CloudBees Previews can generate an environment using the following configuration:

apiVersion: 1.0.0                              (1)

previews:
  - name: web                                  (2)
    container:
      image: acme/acme-web:${{env.commit.sha}} (3)
      port: 80                                 (4)▼

1	File format version, currently 1.0.0.
2	Name of the preview context. Use `default` if you want to request a preview without explicitly providing a name.
3	Image you want to deploy into the preview environment. Note the use of ${{env.commit.sha}}>. This value gets interpolated by CloudBees Previews when it creates the environment. It is replaced with the pull request’s HEAD Git SHA. CloudBees Previews waits for this image during the environment creation and eventually times out with an error if this image does not become available.
4	Port exposed by the application.

Your CI pipeline’s responsibility is to generate and push the image specified in .preview.yaml.

Depending on how your CI solution checks out the pull request, the Git HEAD of the CI checkout might not be identical to the HEAD of the pull request. For example, your CI system might rebase or merge the pull request into the latest changes on the main branch. In this case, a new commit SHA that CloudBees Previews is not aware of will be generated, and you must determine the HEAD commit SHA of the original pull request and use it to tag the image.

For a full reference of the .preview.yaml syntax, see Previews YAML.