Merge pull request #117 from depot/docs-sync-updates

Update content from depot/app

Author: kylegalbraith

Diff for: content/cache/authentication.mdx

@@ -19,6 +19,7 @@ Depot Cache supports authenticating with user tokens and organization tokens. Ad
 For specific details on how to configure your build tools to authenticate with Depot Cache, refer to the following guides:
 
 - [Bazel](/docs/cache/reference/bazel)
+- [Go](/docs/cache/reference/gocache)
 - [Gradle](/docs/cache/reference/gradle)
 - [Pants](/docs/cache/reference/pants)
 - [sccache](/docs/cache/reference/sccache)

Diff for: content/cache/overview.mdx

@@ -1,7 +1,7 @@
 ---
 title: Depot Cache
 ogTitle: Overview of Depot remote caching
-description: Learn how to use Depot remote cache for exponentially faster builds for tools like Bazel, Turborepo, sccache, Pants, and Gradle.
+description: Learn how to use Depot remote cache for exponentially faster builds for tools like Bazel, Go, Turborepo, sccache, Pants, and Gradle.
 ---
 
 import {CacheToolLogoGrid} from '~/components/docs/CacheToolLogoGrid'
@@ -12,7 +12,7 @@ One of the biggest benefits of adopting advanced build tools like Bazel is the a
 
 ## Supported tools
 
-Depot Cache integrates with build tools that support remote caching like Bazel, Turborepo, sccache, Pants, and Gradle. For information about how to configure each tool to use Depot Cache, see the tool documentation:
+Depot Cache integrates with build tools that support remote caching like Bazel, Go, Turborepo, sccache, Pants, and Gradle. For information about how to configure each tool to use Depot Cache, see the tool documentation:
 
 <CacheToolLogoGrid />
 

Diff for: content/cache/reference/gocache.mdx

@@ -0,0 +1,47 @@
+---
+title: Go Cache
+ogTitle: Remote caching for Go builds and tests
+description: Learn how to use Depot remote caching for Go
+---
+
+## Configuring Go to use Depot Cache
+
+Depot Cache can be used with Go from Depot's managed GitHub Actions runners, from your local machine, or from any CI/CD system.
+
+### From Depot-managed Actions runners
+
+[Depot GitHub Actions runners](/docs/github-actions/overview) are pre-configured to use Depot Cache with Go - each runner is launched with the `GOCACHEPROG` environment variable pre-populated with the connection details for Depot Cache.
+
+If this automatic configuration is incompatible with your specific setup, you can disable automatic configuration in your organization settings page and manually configure `GOCACHEPROG` to use Depot Cache as described below.
+
+### From your local machine or any CI/CD system
+
+To manually configure Go to use Depot Cache, set the `GOCACHEPROG` in your environment:
+
+```shell
+export GOCACHEPROG="depot gocache"
+```
+
+The `depot` CLI will need to have [authorization](/docs/cli/authentication) to write to the cache.
+
+If you are a member of multiple organizations, and you are authenticating with a user token, you must instead specify which organization should be used for cache storage as follows:
+
+```shell
+export GOCACHEPROG='depot gocache --organization ORG_ID'
+```
+
+To clean the cache, you can use the typical `go clean` workflow:
+
+```shell
+go clean -cache
+```
+
+To set verbose output, add the --verbose option:
+
+```shell
+export GOCACHEPROG='depot gocache --verbose'
+```
+
+## Using Depot Cache with Go
+
+Once Go is configured to use Depot Cache, you can then run your builds as you normally would. Go will automatically communicate with `GOCACHEPROG` to fetch from Depot Cache and reuse any stored build artifacts from your previous builds.

Diff for: content/cli/authentication.mdx

@@ -43,6 +43,7 @@ To add a trust relationship for GitHub Actions, you can go through the following
 5. Enter a GitHub User or Organization for the trust relationship
 6. Enter the name of the GitHub repository that will build images via Depot (Note: this is the repository name, not the full URL and it must match the repository name exactly)
 7. Click Add trust relationship
+8. Ensure your workflow has permission to use this OIDC trust relationship by setting the permission `id-token: write`.
 
 ### Adding a trust relationship for CircleCI
 

Diff for: content/cli/reference.mdx

@@ -101,7 +101,7 @@ If you want to build a specific target in the bake file, you can specify it in t
 depot bake -f docker-bake.hcl original
 ```
 
-You can also save all of the targets built in a bake or compose file to the [ephemeral registry](/docs/container-builds/how-to-guides/ephemeral-registry) for later use with the `--save` flag:
+You can also save all of the targets built in a bake or compose file to the [Depot Registry](/docs/registry/overview) for later use with the `--save` flag:
 
 ```shell
 depot bake -f docker-bake.hcl --save
@@ -164,7 +164,7 @@ This command accepts all the command line flags as Docker's `docker buildx bake`
 | `provenance` | Shorthand for "--set=\*.attest=type=provenance" |
 | `pull` | Always attempt to pull all referenced images |
 | `push` | Shorthand for "--set=\*.output=type=registry" |
-| `save` | Saves the build to the Depot ephemeral registry
+| `save` | Saves the build to the Depot Registry
 | `sbom` | Shorthand for "--set=\*.attest=type=sbom" |
 | `sbom-dir` | Directory to store SBOM attestations |
 | `set` | Override target value (e.g., "targetpattern.key=value") |
@@ -236,7 +236,7 @@ This command accepts all the command line flags as Docker's `docker buildx build
 | `pull` | Always attempt to pull all referenced images |
 | `push` | Shorthand for "--output=type=registry" |
 | `quiet` | Suppress the build output and print image ID on success |
-| `save` | Saves the build to the Depot ephemeral registry |
+| `save` | Saves the build to the Depot Registry |
 | `sbom` | Shorthand for "--attest=type=sbom" |
 | `sbom-dir` | Directory to store SBOM attestations |
 | `secret` | Secret to expose to the build (format: "id=mysecret[,src=/local/secret]") |
@@ -270,6 +270,42 @@ Reset the cache of a specific project ID
 depot cache reset --project 12345678910
 ```
 
+### `depot gocache`
+
+Configure Go tools to use Depot Cache. The Go tools will use the remote cache service to store and retrieve build artifacts.
+
+_Note: This requires Go 1.24 or later._
+
+Set the environment variable `GOCACHEPROG` to `depot gocache` to configure Go to use Depot Cache.
+
+```shell
+export GOCACHEPROG='depot gocache'
+```
+
+Next, run your Go build commands as usual.
+
+```shell
+go build ./...
+```
+
+To set verbose output, add the --verbose option:
+
+```shell
+export GOCACHEPROG='depot gocache --verbose'
+```
+
+To clean the cache, you can use the typical `go clean` workflow:
+
+```shell
+go clean -cache
+```
+
+If you are in multiple Depot organizations and want to specify the organization, you can use the `--organization` flag.
+
+```shell
+export GOCACHEPROG='depot gocache --organization ORG_ID'
+```
+
 ### `depot configure-docker`
 
 Configure Docker to use Depot's remote builder infrastructure. This command installs Depot as a Docker CLI plugin (i.e., `docker depot ...`), sets the Depot plugin as the default Docker builder (i.e., `docker build`), and activates a buildx driver (i.e. `docker buildx buildx ...`).
@@ -399,7 +435,7 @@ depot list projects
 
 ### `depot pull`
 
-Pull an image from the ephemeral registry by build ID in a project.
+Pull an image from the Depot Registry by build ID in a project.
 
 **Example**
 
@@ -437,7 +473,7 @@ Additional flags that can be used with this command.
 
 ### `depot pull-token`
 
-Generate a short-lived token to pull an image from the ephemeral registry.
+Generate a short-lived token to pull an image from the Depot Registry.
 
 **Example**
 
@@ -466,7 +502,7 @@ Additional flags that can be used with this command.
 
 ### `depot push`
 
-Push an image from the ephemeral registry to a remote registry. It uses registry credentials stored in Docker when pushing to registries. If you have not already authenticated with your registry, you should do so with `docker login` before running `depot push`.
+Push an image from the Depot Registry to another registry. It uses registry credentials stored in Docker when pushing to registries. If you have not already authenticated with your registry, you should do so with `docker login` before running `depot push`.
 
 **Example**
 

Diff for: content/container-builds/how-to-guides/docker-compose.mdx

@@ -98,7 +98,7 @@ However, `depot configure-docker` does directly integrate with any tools that us
 
 ## Building and testing `docker compose` on GitHub Actions
 
-With the `depot/bake-action` action and the `--save` flag, we can build all of the services in a Compose file in parallel and save them to the Depot ephemeral registry. Then, with the `depot/pull-action`, we can pull all of the images back into the local Docker daemon for testing in subsequent jobs.
+With the `depot/bake-action` action and the `--save` flag, we can build all of the services in a Compose file in parallel and save them to the Depot Registry. Then, with the `depot/pull-action`, we can pull all of the images back into the local Docker daemon for testing in subsequent jobs.
 
 ```yaml
 name: Depot example compose
@@ -117,7 +117,7 @@ jobs:
     steps:
       - uses: actions/checkout@v4
       - uses: depot/setup-action@v1
-      - name: Build, cache, and save all compose images to the depot ephemeral registry.
+      - name: Build, cache, and save all compose images to the Depot Registry.
         uses: depot/bake-action@v1
         id: bake
         with:
@@ -130,14 +130,14 @@ jobs:
     steps:
       - uses: actions/checkout@v4
       - uses: depot/setup-action@v1
-      - name: Pull all compose service images locally from the ephemeral registry.
+      - name: Pull all compose service images locally from the Depot Registry.
         uses: depot/pull-action@v1
         with:
           build-id: ${{ needs.build-services.outputs.build-id }}
       - name: Run compose up (images should not rebuild)
         run: |
           docker compose up -d
-      - name: If successful push the srv1 compose service target image to ghcr.io from ephemeral registry
+      - name: If successful, push the srv1 compose service target image to ghcr.io from Depot Registry
         run: |
           echo ${{ secrets.GITHUB_TOKEN }} | docker login ghcr.io -u $ --password-stdin
           depot push --target srv1 -t ghcr.io/depot/srv1:latest ${{ steps.build.outputs.build-id }}

Diff for: content/container-builds/how-to-guides/ephemeral-registry.mdx

@@ -68,11 +68,11 @@ We can accelerate your image builds for other developer tools like Dev Container
 
 We offer autoscaling for our remote container builds. By default, all builds for a project are routed to a single BuildKit host per architecture you're building. With build autoscaling, you can configure the maximum number of builds to run on a single host before launching another host with a copy of your layer cache. This can help you parallelize builds across multiple hosts and reduce build times even further by giving them dedicated resources.
 
-### Ephemeral registry
+### Depot Registry
 
-We offer a built-in ephemeral registry that you can use to save the images from your `depot build` and `depot bake` commands to a temporary registry. You can then pull those images back down or push them to your final registry as you see fit.
+We offer a built-in registry that you can use to save the images from your `depot build` and `depot bake` commands to a registry. You can then pull those images back down or push them to your final registry as you see fit.
 
-[Learn more about the ephemeral registry](/docs/container-builds/how-to-guides/ephemeral-registry)
+[Learn more about the Depot Registry](/docs/registry/overview)
 
 ## How does it work?