From 1d90bbccceb0354e0b17b4148190927650d7003d Mon Sep 17 00:00:00 2001 From: Sergey Dolin Date: Tue, 29 Aug 2023 19:44:05 +0200 Subject: [PATCH] Update README.md with more sample --- README.md | 137 +++++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 136 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 6dafed1f9..b3423670a 100644 --- a/README.md +++ b/README.md @@ -171,11 +171,146 @@ steps: - uses: actions/setup-go@v4 with: go-version: '1.17' - check-latest: true cache-dependency-path: subdir/go.sum - run: go run hello.go ``` +**Caching in multirepos** +`cache-dependency-path` input assepts glob patterns and multi-line values: + +```yaml +steps: + - uses: actions/checkout@v3 + - uses: actions/setup-go@v4 + with: + go-version: '1.17' + cache-dependency-path: **/go.sum + - run: go run hello.go + ``` + +```yaml +steps: + - uses: actions/checkout@v3 + - uses: actions/setup-go@v4 + with: + go-version: '1.17' + cache-dependency-path: | + subdir1/go.sum + subdir2/go.mod + - run: go run hello.go + ``` + +## Multi-target builds +`cache-dependency-path` input used to generate unuque cache key and it is not limited to only +dependencies files. The common case is to add a file containing the extr info about the specific +build, for example build target. + +```yaml +env: + GOOS: ... + GOARCH: ... + +steps: + - run: echo "$GOOS $GOARCH"> /tmp/env + + - uses: actions/setup-go@v4 + with: + go-version: '1.17' + cache-dependency-path: go.sum /tmp/env + - run: go run hello.go +``` + +## Invalidate cache when source code changes +Besides the dependencise the action caches the build outputs +([GOCACHE](https://pkg.go.dev/cmd/go#hdr-Build_and_test_caching) directory) but by default this +cache is not update in order to avoid unpredictable and frequent cache invaldation. Nevertheless +including the source code files into `cache-dependency-path` input. + +```yaml +- uses: actions/setup-go@v4 + with: + go-version: '1.17' + cache-dependency-path: go.sum **/*.go +- run: go run hello.go +``` + +But more practically to manage the cache with the text file manually updated according to the amount +of changes made in the repo. + +```yaml +- uses: actions/setup-go@v4 + with: + go-version: '1.17' + cache-dependency-path: go.sum cache-version.txt +- run: go run hello.go +``` + +## Caching with actions/cache +The caching capabilities of the action are limited for the simplest builds and can be ineffective in the real world +use cases. If the build requires fine-grained turning the built-in caching should be disabled and +[actions/cache](https://github.com/actions/cache) should be used. + +Here the sample `actions/cache` configuration with the extending options allowing + - configuring paths to cache + - have different caches for rare changes dependencies and more often changed intermediate build files + - use `restore-key` input to restore the previous cache even if the current key cache has changed + - have different caches intermediate build files of different architectures + - have custom cache key for parallel builds + +```yaml +build: + env: + GOOS: ... + GOARCH: ... + + steps: + - uses: actions/setup-go@v4 + with: + go-version: "1.17" + cache: false + + - name: Get Go cached paths + run: | + echo "cache=$(go env GOCACHE)" >> $GITHUB_ENV + echo "modcache=$(go env GOMODCACHE)" >> $GITHUB_ENV + + - name: Set up dependencies cache + uses: actions/cache@v3 + with: + path: | + ${{ env.cache }} + key: setup-go-deps-${{ runner.os }}-go-${{ hashFiles('go.sum go.mod') }} + restore-keys: | + setup-go-deps-${{ runner.os }}-go- + + - name: + run: echo "$GOOS $GOARCH"> /tmp/env + + - name: Set up intermediate built files cache + uses: actions/cache@v3 + with: + path: | + ${{ env.modcache }} + key: setup-go-build-${{ env.GOOS }}-${{ env.GOARCH }}-${{ runner.os }}-go-${{ hashFiles('**/*.go /tmp/env') }} + restore-keys: | + setup-go-build-${{ env.GOOS }}-${{ env.GOARCH }} + +``` + +## Restore-only caches +If there are several builds on the same repo it might make sense to create a cache in one build and use it in the +others. The action [actions/cache/restore](https://github.com/marketplace/actions/cache-restore) +should be used in this case. + +## Generate different caches +This advanced use case assumes manual definition of cache key and requires the use of +[actions/cache](https://github.com/actions/cache/blob/main/examples.md#go---modules) + +## Parallel builds +To avoid race conditions during the parallel builds they should either +[generate their own caches](#generate-different-caches), or create the cache +for only one build and [restore](#restore-only-caches) that cache in the other builds. + ## Getting go version from the go.mod file The `go-version-file` input accepts a path to a `go.mod` file or a `go.work` file that contains the version of Go to be