Cirq

# Continuous integration scripts

The scripts in this directory are used by the workflows in
[`../../.github/workflows/`](../../.github/workflows/).

# Cirq infra

_Cirq-infra_ is the name of a the Google Cloud Platform (GCP) project implemented and managed by the
Google Quantum AI team in support of open-source projects like Cirq. It was originally introduced
around the years 2020–2021 to implement several systems:

*   Automatic merging of pull requests on GitHub
*   Automatic labeling of the sizes of changes in pull requests
*   Running [Triage Party](https://github.com/google/triage-party), a tool for collaborative
    triaging of GitHub issues and pull requests

The automerge and automatic labeling capabilities were implemented using a homegrown tool called
`pr_monitor`, whose source code was in the [`dev_tools`](../) subdirectory of the Cirq
repository. In 2025, the automerge system was discontinued in favor of using GitHub's "merge
queues", and the size-labeling facility was reimplemented using a GitHub Actions workflow.
`pr_monitor` was retired in the Cirq 1.5 release.

_Cirq-infra_ is still being used to support Triage Party.

## GCP Configuration

Access is granted to Cirq maintainers only.

### Requirements

The tools below are required to manage our infra:

*   Cloud SDK: https://cloud.google.com/sdk/docs/quickstart
*   kubectl: `gcloud components install kubectl`.
*   skaffold: `gcloud components install skaffold`.

### GKE Cluster

We have a 3 node GKE cluster called cirq-infra. To connect to it using kubectl
use:

```shell
gcloud container clusters get-credentials cirq-infra --zone us-central1-a --project cirq-infra
```

Note that we have Workload Identity setup so that in order to access Cloud APIs
from workloads, you'll have to add permissions to the
[email protected] service account.
Currently, it is able to access Secrets, and no other APIs.

### Secret manager

It is important to know that the Github API key in case of the Kubernetes
deployment is stored in the Cloud Secret Manager under `cirq-bot-api-key`.

# Cirq Triage Party

[Triage Party](https://github.com/google/triage-party) is an issue and pull request triaging tool
for GitHub. For more information about the triaging process used in the Cirq project, please refer
to the [triage process documentation for Cirq](../../docs/dev/triage.md).

## Local testing

It is possible to run an instance of Triage Party on your local host. This is useful for testing
configuration changes.

1.  Generate a personal access token on GitHub with read-only permissions for `public_repo`. (Please
    refer to the GitHub documentation for [personal access tokens] for information on how to do
    that.) The token will be a string of characters that begins with the letters `gho_`.

2.  Store this token string in the environment variable `GITHUB_TOKEN`:

    ```shell
    export GITHUB_TOKEN="yourtokenhere"
    ```

3.  Run Triage Party locally in a container using either Podman or Docker. The script
    `./run-local.sh` makes this convenient; it pulls an image for Triage Party from a container
    registry and runs it with the appropriate Cirq configuration files. (Note: this produces
    _a lot_ of output.)

    ```shell
    ./run-local.sh
    ```

After some time and many lines of logs printed, if all went well, the output should end with a line
that looks more or less something like this:

```text
I0601 21:40:01.954553       1 updater.go:250] update cycle #1 took 7.005642265s
```

The exact numbers printed in the output are not important; what matters is that it did not end with
an error message and did not return to the shell, but rather paused with `update cycle #1` as the
final message. The Triage Party server will then be listening for web browser connections on port
8080 on your local host. It will produce more output as it detects that files have changed.

[personal access tokens]: https://help.github.com/en/articles/creating-a-personal-access-token-for-the-command-line

## Cloud configuration & Setup

The deployment of Cirq's Triage Party instance on a Google Cloud server is managed using Kubernetes,
an open-source platform that automates the deployment, scaling, and management of containerized
applications. Specifically, we use the tools Kustomize and Skaffold.

### 1. Application Configuration

To customize the Triage Party dashboard (e.g., modifying collections, rules, and members), edit the
standalone YAML configuration file located at [kubernetes/02_deployment/config.yaml][config].
This file is read by the program `kustomize` to generate the `triage-party-config` ConfigMap for
Kubernetes.

Please refer to the official [Triage Party documentation] for details on the available configuration
options.

[Triage Party documentation]: https://github.com/google/triage-party/blob/main/docs/config.md

### 2. Static Resources & Theming (CSS & Favicon)

Extra resources like custom styling and the site's favicon are also managed automatically via
Kustomize:

-   **Custom CSS**: Overrides to the default Triage Party look and feel are defined in
    [kubernetes/02_deployment/custom.css][custom_css] as a ConfigMap.

-   **Favicon**: The favicon is bundled directly from the image file
    [kubernetes/02_deployment/cirq-icon-very-small.png][cirq_icon]. Kustomize reads this binary
    file and creates the `triage-party-favicon` ConfigMap automatically as defined in
    [kubernetes/kustomization.yaml][kustomization].

There is no need to manually run `kubectl create configmap` commands for these resources.

[cirq_icon]: kubernetes/02_deployment/cirq-icon-very-small.png
[config]: kubernetes/02_deployment/config.yaml
[custom_css]: kubernetes/02_deployment/custom.css
[kustomization]: kubernetes/kustomization.yaml

### 3. GitHub Token Secret (One-time Setup)

Triage Party requires a GitHub personal access token so that it can query the GitHub API to get data
about issues and pull requests. The token creation and assignment is a one-time setup. You must
create a Kubernetes Secret containing a GitHub token. Follow these steps:

1.  Obtain a new token from GitHub.

2.  Set the environment variable `GITHUB_TOKEN` to the token to be used.

3.  Run the following command in a terminal on your local host:

    ```shell
    # Authenticate to Google Cloud.
    gcloud auth login

    # Provision your underlying Application Default Credentials (ADC).
    gcloud auth application-default login

    # Authenticate your local terminal with the Kubernetes cluster running
    # on Google Kubernetes Engine (GKE) and save values in ~/.kube/config.
    gcloud container clusters get-credentials cirq-infra --zone us-central1-a

    # Finally, create the secret inside the cluster.
    kubectl create secret generic triage-party-github-token \
        -n triage-party --from-literal=token="${GITHUB_TOKEN}"
    ```

## Deployment

Google Cloud Build is Google Cloud Platform's (GCP) serverless CI/CD service. When code is pushed,
Cloud Build automatically imports the changes, executes the build files, compiles the necessary
containers, and safely applies them to the production environment without manual intervention.
Please refer to the [cirq-infra documentation](../cirq-infra/README.md) to find out more about the
software tools needed and how to install them.

### Google Cloud Build deployment

On every push to the `main` branch that involves files in `dev_tools/triage-party/`, the Cirq Triage
Party instance is automatically redeployed using the steps defined in the file
[cloudbuild-deploy.yaml](./cloudbuild-deploy.yaml). This is achieved thanks to a Cloud Build Trigger
defined in the `cirq-infra` project in GCP. Thus, when changes to the Triage Party configuration are
merged into the `main` branch on GitHub, the server instance will be updated automatically.

### Manual Deployment

It is possible to update the Triage Party deployment manually (e.g., for applying an immediate fix).
This can be done using the command-line tool `skaffold`. Execute these commands from the top level
of the Cirq repository:

```shell
# Authenticate to Google Cloud.
gcloud auth login

# Provision your underlying Application Default Credentials (ADC).
gcloud auth application-default login

# Authenticate your local terminal with the remote Kubernetes cluster running
# on Google Kubernetes Engine (GKE) and save values in ~/.kube/config.
gcloud container clusters get-credentials cirq-infra --zone us-central1-a

# Bundle the config, generate ConfigMaps, and deploy.
skaffold run --force -f=dev_tools/triage-party/skaffold.yaml
```