Bazel GitOps Rules

In a trunk-based model, create_gitops_prs is run on the main branch. It identifies gitops targets that match a specific --release_branch (which corresponds to the release_branch_prefix attribute in k8s_deploy) and groups them by their deploy_branch attribute.

Key Parameters for CI Integration:

• --workspace: The root directory of your Git workspace.
• --git_repo: The remote URL of the repository.
• --git_mirror: Path to a local reference repository to speed up cloning.
• --git_server: The type of Git server (github, gitlab, or bitbucket).
• --release_branch: Matches the release_branch_prefix in your k8s_deploy targets.
• --gitops_pr_into: The target branch for the new PR.
• --branch_name: The value used in the PR commit message.
• --git_commit: The specific commit ID to use in the PR.
• --dry_run: Tests the tool without creating actual PRs (recommended for CI testing).

GIT_ROOT_DIR=$(git rev-parse --show-toplevel)
GIT_COMMIT_ID=$(git rev-parse HEAD)
GIT_BRANCH_NAME=$(git rev-parse --abbrev-ref HEAD)
if [ "${GIT_BRANCH_NAME}" == "master"]; then
    bazel run //gitops/prer:create_gitops_prs -- \
        --workspace $GIT_ROOT_DIR \
        --git_repo https://github.com/example/repo.git \
        --git_mirror $GIT_ROOT_DIR/.git \
        --git_server github \
        --release_branch master \
        --gitops_pr_into master \
        --gitops_pr_title "This is my pull request title" \
        --gitops_pr_body "This is my pull request body message" \
        --branch_name ${GIT_BRANCH_NAME} \
        --git_commit ${GIT_COMMIT_ID}
fi

When a trunk-based model is unsuitable, you can use the create_gitops_prs tool to create GitOps pull requests from release branches before they are merged into main.

To implement this, use the --release_branch parameter to specify the base release branch (e.g., release/team) and the --deployment_branch_suffix parameter to handle the unique suffix of the current release branch (e.g., -20200101). This allows the tool to target specific deployment branches like deploy/monitoring-stage-20200101 for PRs into master.

In your k8s_deploy rules, use the release_branch_prefix attribute to ensure deployments are only selected when the tool is running against the matching release branch prefix.

# Example shell command for CI pipeline running on a release branch
if [ "${RELEASE_BRANCH}" == "release/team"]; then
    bazel run //gitops/prer:create_gitops_prs -- \
        --workspace $GIT_ROOT_DIR \
        --git_repo https://github.com/example/repo.git \
        --git_mirror $GIT_ROOT_DIR/.git \
        --git_server github \
        --release_branch ${RELEASE_BRANCH} \
        --deployment_branch_suffix=${RELEASE_BRANCH_SUFFIX} \
        --gitops_pr_into master \
        --gitops_pr_title "This is my pull request title" \
        --gitops_pr_body "This is my pull request body message" \
        --branch_name ${GIT_BRANCH_NAME} \
        --git_commit ${GIT_COMMIT_ID}
fi

The create_gitops_prs tool automates the creation of pull requests in your GitOps repository. This is typically run as the final step in a CI pipeline.

To see all available command-line options, run:

bazel run @rules_gitops//gitops/prer:create_gitops_prs -- --help

Supported Git Servers

Use the --git_server flag to specify the provider. The available options are github, gitlab, and bitbucket. Each provider requires specific parameters:

Note: Integration testing support is currently experimental and the public API is subject to change (no semver guarantee).

To perform integration testing, you must use two rules in tandem:

1. k8s_test_setup: Manages the Kubernetes environment. It creates a temporary namespace (formatted as [username][5 random digits]) and a kubeconfig file. It also deploys the objects specified in the objects attribute.
2. A test rule (e.g., java_test): Executes the actual test logic. It must consume the shell script produced by k8s_test_setup as data and use the $(location ...) Bazel function to pass the script path to the test runner.

Your test code is responsible for:

• Launching the setup script.
• Monitoring the script's console output for pod readiness events.

k8s_test_setup(
    name = "service_it.setup",
    kubeconfig = "@k8s_test//:kubeconfig",
    objects = [
        "//service:mynamespace",
    ],
)

java_test(
    name = "service_it",
    srcs = ["ServiceIT.java"],
    data = [":service_it.setup"],
    jvm_flags = ["-Dk8s.setup=$(location :service_it.setup)"],
)

To connect container images built with rules_img to your k8s_deploy targets, use the k8s_push_info adapter. This ensures that image pushes and registry information are correctly associated with the deployment.

load("@rules_gitops//adapters:rules_img.bzl", "k8s_push_info")
load("@rules_gitops//gitops:defs.bzl", "k8s_deploy")
load("@rules_img//img:image.bzl", "image_manifest")
load("@rules_img//img:push.bzl", "image_push")

image_manifest(
    name = "my_image",
    # ... image configuration
)

image_push(
    name = "push",
    image = ":my_image",
    registry = "my-registry.com",
    repository = "my-org/my-image",
)

k8s_push_info(
    name = "k8s_image",
    image = ":my_image",
    push = ":push",
    registry = "my-registry.com",
    repository = "my-org/my-image",
)

k8s_deploy(
    name = "my_deployment",
    cluster = "my-cluster",
    images = [":k8s_image"],
    manifests = ["deployment.yaml"],
    namespace = "{BUILD_USER}",
)