> For the complete CircleCI developer hub index, see [llms.txt](https://circleci.com/developer/llms.txt)

# circleci/gcp-gcr

An orb for managing images with Google Container Registry (GCR).


## Commands

### build-image

Build a Docker image

| Parameter | Type | Default | Description |
|---|---|---|---|
| `attach-workspace` | boolean | false | Boolean for whether or not to attach to an existing workspace. Default is false.
 |
| `docker-context` | string | . | Path to the directory containing your build context, defaults to . (working directory)
 |
| `dockerfile` | string | Dockerfile | Name of dockerfile to use, defaults to Dockerfile |
| `extra_build_args` | string |  | Extra flags to pass to docker build. For examples, see https://docs.docker.com/engine/reference/commandline/build
 |
| `google-project-id` | env_var_name | GOOGLE_PROJECT_ID | The Google project ID to connect with via the gcloud CLI |
| `image` | string |  | A name for your Docker image |
| `no_output_timeout` | string | 10m | Pass through a default timeout if your Docker build does not output anything for more than 10 minutes.
 |
| `path` | string | . | Path to the directory containing your Dockerfile, defaults to . (working directory)
 |
| `registry-url` | string | gcr.io | The GCR registry URL from ['', us, eu, asia].gcr.io |
| `repository` | string |  | The Artifact Registry requires a HOST-NAME/PROJECT-ID/REPOSITORY/IMAGE format. If pushing to the Artifact Registry, the repository to push the image to
 |
| `tag` | string | latest | A Docker image tag |
| `workspace-root` | string | . | Workspace root path that is either an absolute path or a path relative to the working directory. Defaults to '.' (the working directory)
 |

### gcr-auth

Configure Docker to use gcloud as a credential helper.


| Parameter | Type | Default | Description |
|---|---|---|---|
| `components` | string |  | The list of gcloud components to install. Space separated. See https://cloud.google.com/sdk/docs/components for additional
 |
| `gcloud-service-key` | env_var_name | GCLOUD_SERVICE_KEY | The gcloud service key |
| `gcp_cred_config_file_path` | string | ~/gcp_cred_config.json | Output location of OIDC credentials. |
| `google-compute-region` | env_var_name | GOOGLE_COMPUTE_REGION | The Google compute region to connect with via the gcloud CLI
 |
| `google-compute-zone` | env_var_name | GOOGLE_COMPUTE_ZONE | The Google compute zone to connect with via the gcloud CLI
 |
| `google-project-id` | env_var_name | GOOGLE_PROJECT_ID | Environment variable name for the Google project ID to connect with via the gcloud CLI
 |
| `google_project_number` | env_var_name | GOOGLE_PROJECT_NUMBER | Name of environment variable storing the Google project number
used to configure OIDC.
 |
| `registry-url` | string | gcr.io | The GCR registry URL from ['', us, eu, asia].gcr.io, or an artifact registry url from [GOOGLE_COMPUTE_REGION, us, eu, asia]-docker.pkg.dev
 |
| `service_account_email` | env_var_name | OIDC_SERVICE_ACCOUNT_EMAIL | Environment variable containing OIDC service account email. |
| `use_oidc` | boolean | false | Set to true to enable OIDC |
| `version` | string | latest | The version of the gcloud CLI to install. If left to "latest", the latest version will be installed. Otherwise, provide the full version number as it appears in the URL on this page: https://cloud.google.com/sdk/docs/downloads-versioned-archives
 |
| `workload_identity_pool_id` | env_var_name | OIDC_WIP_ID | Environment variable containing OIDC configured workload identity pool is stored.
 |
| `workload_identity_pool_provider_id` | env_var_name | OIDC_WIP_PROVIDER_ID | Environment variable containing OIDC configured workload identity pool provider ID is stored.
 |

### push-image

Push a container image to the GCR registry

| Parameter | Type | Default | Description |
|---|---|---|---|
| `digest-path` | string |  | (Optional) The path to save the RepoDigest of the pushed image |
| `google-project-id` | env_var_name | GOOGLE_PROJECT_ID | The Google project ID to connect with via the gcloud CLI |
| `image` | string |  | A name for your docker image |
| `registry-url` | string | gcr.io | The GCR registry URL from ['', us, eu, asia].gcr.io |
| `repository` | string |  | The Artifact Registry requires a HOST-NAME/PROJECT-ID/REPOSITORY/IMAGE format. If pushing to the Artifact Registry, the repository to push the image to
 |
| `tag` | string | latest | Comma-separated list of docker image tags. The contents of each will be evaluated. |

### tag-image

Add a tag to an existing published image

| Parameter | Type | Default | Description |
|---|---|---|---|
| `google-project-id` | env_var_name | GOOGLE_PROJECT_ID | The Google project ID to connect with via the gcloud CLI |
| `image` | string |  | A Docker image name |
| `registry-url` | string | gcr.io | The GCR registry URL from ['', us, eu, asia].gcr.io |
| `repository` | string |  | The Artifact Registry requires a HOST-NAME/PROJECT-ID/REPOSITORY/IMAGE format. If pushing to the Artifact Registry, the repository to push the image to
 |
| `source-tag` | string |  | An existing Docker image tag. The contents will be evaluated. |
| `target-tag` | string |  | A new Docker image tag. The contents will be evaluated. |

## Jobs

### add-image-tag

Install GCP CLI, if needed, and configure. Adds a tag to an existing image.


| Parameter | Type | Default | Description |
|---|---|---|---|
| `executor` | executor | default | executor to use for this job |
| `gcloud-service-key` | env_var_name | GCLOUD_SERVICE_KEY | The gcloud service key |
| `gcloud_components` | string |  | The list of gcloud components to install. Space separated. See https://cloud.google.com/sdk/docs/components for additional info.
 |
| `gcloud_version` | string | latest | Version of gcloud CLI to install.
 |
| `gcp_cred_config_file_path` | string | ~/gcp_cred_config.json | Output location of OIDC credentials. |
| `google-compute-region` | env_var_name | GOOGLE_COMPUTE_REGION | The Google compute zone to connect with via the gcloud CLI |
| `google-compute-zone` | env_var_name | GOOGLE_COMPUTE_ZONE | The Google compute zone to connect with via the gcloud CLI |
| `google-project-id` | env_var_name | GOOGLE_PROJECT_ID | The Google project ID to connect with via the gcloud CLI |
| `google_project_number` | env_var_name | GOOGLE_PROJECT_NUMBER | Name of environment variable storing the Google project number
used to configure OIDC.
 |
| `image` | string |  | A name for your Docker image |
| `registry-url` | string | gcr.io | The GCR registry URL from ['', us, eu, asia].gcr.io |
| `service_account_email` | env_var_name | OIDC_SERVICE_ACCOUNT_EMAIL | Environment variable containing OIDC service account email. |
| `source-tag` | string |  | An existing Docker image tag |
| `target-tag` | string |  | A new Docker image tag |
| `use_oidc` | boolean | false | Set to true to enable OIDC |
| `workload_identity_pool_id` | env_var_name | OIDC_WIP_ID | Environment variable containing OIDC configured workload identity pool is stored.
 |
| `workload_identity_pool_provider_id` | env_var_name | OIDC_WIP_PROVIDER_ID | Environment variable containing OIDC configured workload identity pool provider ID is stored.
 |

### build-and-push-image

Install GCP CLI, if needed, and configure. Build and push image to repository.


| Parameter | Type | Default | Description |
|---|---|---|---|
| `attach-workspace` | boolean | false | Boolean for whether or not to attach to an existing workspace. Default is false.
 |
| `digest-path` | string |  | (Optional) The path to save the RepoDigest of the pushed image |
| `docker-context` | string | . | Path to the directory containing your build context, defaults to . (working directory)
 |
| `dockerfile` | string | Dockerfile | Name of dockerfile to use, defaults to Dockerfile |
| `executor` | executor | default | executor to use for this job |
| `extra_build_args` | string |  | Extra flags to pass to docker build. For examples, see https://docs.docker.com/engine/reference/commandline/build
 |
| `gcloud-service-key` | env_var_name | GCLOUD_SERVICE_KEY | The gcloud service key |
| `gcloud_components` | string |  | The list of gcloud components to install. Space separated. See https://cloud.google.com/sdk/docs/components for additional info.
 |
| `gcloud_version` | string | latest | Version of gcloud CLI to install.
 |
| `gcp_cred_config_file_path` | string | ~/gcp_cred_config.json | Output location of OIDC credentials. |
| `google-compute-region` | env_var_name | GOOGLE_COMPUTE_REGION | The Google compute zone to connect with via the gcloud CLI |
| `google-compute-zone` | env_var_name | GOOGLE_COMPUTE_ZONE | The Google compute zone to connect with via the gcloud CLI |
| `google-project-id` | env_var_name | GOOGLE_PROJECT_ID | The Google project ID to connect with via the gcloud CLI |
| `google_project_number` | env_var_name | GOOGLE_PROJECT_NUMBER | Name of environment variable storing the Google project number
used to configure OIDC.
 |
| `image` | string |  | A name for your Docker image |
| `no_output_timeout` | string | 10m | Pass through a default timeout if your Docker build does not output anything for more than 10 minutes.
 |
| `path` | string | . | Path to the directory containing your Dockerfile, defaults to . (working directory)
 |
| `registry-url` | string | gcr.io | The GCR registry URL from ['', us, eu, asia].gcr.io, or an artifact registry url from [GOOGLE_COMPUTE_REGION, us, eu, asia]-docker.pkg.dev
 |
| `remote-docker-version` | string | docker24 | Specify the remote docker version. See: https://circleci.com/docs/2.0/building-docker-images/#docker-version
 |
| `repository` | string |  | The Artifact Registry requires a HOST-NAME/PROJECT-ID/REPOSITORY/IMAGE format. If pushing to the Artifact Registry, the repository to push the image to
 |
| `service_account_email` | env_var_name | OIDC_SERVICE_ACCOUNT_EMAIL | Environment variable containing OIDC service account email. |
| `setup-remote-docker` | boolean | false | Setup and use CircleCI's remote Docker environment for Docker and docker-compose commands? Not required if using the default executor
 |
| `tag` | string | latest | A Docker image tag |
| `use-docker-layer-caching` | boolean | false | Setup docker layer caching for optimized build. Not available if using the default executor.
 |
| `use_oidc` | boolean | false | Set to true to enable OIDC |
| `workload_identity_pool_id` | env_var_name | OIDC_WIP_ID | Environment variable containing OIDC configured workload identity pool is stored.
 |
| `workload_identity_pool_provider_id` | env_var_name | OIDC_WIP_PROVIDER_ID | Environment variable containing OIDC configured workload identity pool provider ID is stored.
 |
| `workspace-root` | string | . | Workspace root path that is either an absolute path or a path relative to the working directory. Defaults to '.' (the working directory)
 |

## Executors

### default

A debian-based machine executor

## Examples

### build-and-push-digest

Log into Google Cloud Plaform, build and push image to GCR, then echo the image digest


```yaml
version: '2.1'
orbs:
  gcp-gcr: circleci/gcp-gcr@x.y.z
jobs:
  build-and-push:
    executor: gcp-gcr/default
    steps:
      - checkout
      - gcp-gcr/gcr-auth
      - gcp-gcr/build-image:
          image: orb-test
          no_output_timeout: 20m
          registry-url: eu.gcr.io
      - gcp-gcr/push-image:
          digest-path: /tmp/digest.txt
          image: orb-test
          registry-url: eu.gcr.io
      - run:
          command: |
            echo "Digest is: $(</tmp/digest.txt)"
workflows:
  commit:
    jobs:
      - build-and-push
```

### optimized-build-and-push

Log into Google Cloud Plaform, then build and push image to GCR. Uses a custom executor to reduce the setup time.


```yaml
version: '2.1'
orbs:
  gcp-gcr: circleci/gcp-gcr@x.y.z
workflows:
  build_and_push_image:
    jobs:
      - gcp-gcr/build-and-push-image:
          context: myContext
          executor: my-executor
          image: my-image
          registry-url: us.gcr.io
          setup-remote-docker: true
          use-docker-layer-caching: true
```

### simple-build-and-push

Log into Google Cloud Plaform, then build and push image to GCR


```yaml
version: '2.1'
orbs:
  gcp-gcr: circleci/gcp-gcr@x.y.z
workflows:
  build_and_push_image:
    jobs:
      - gcp-gcr/build-and-push-image:
          context: myContext
          image: my-image
          registry-url: us.gcr.io
```

### simple-build-and-push-artifact-registry

Log into Google Cloud Plaform, then build and push image to Artifact Registry


```yaml
version: '2.1'
orbs:
  gcp-gcr: circleci/gcp-gcr@x.y.z
workflows:
  build_and_push_image:
    jobs:
      - gcp-gcr/build-and-push-image:
          context: myContext
          image: my-image
          registry-url: us-central1-docker.pkg.dev
          repository: my-repo
```

### tag-existing-image

Log into Google Cloud Plaform, then tag an existing image with "latest"


```yaml
version: '2.1'
orbs:
  gcp-gcr: circleci/gcp-gcr@x.y.z
workflows:
  build_and_push_image:
    jobs:
      - gcp-gcr/tag-image:
          context: myContext
          image: my-image
          registry-url: us.gcr.io
          source-tag: mytag1
          target-tag: mytag2
```