From 3671db66cbd52001b473b82e63a6abeac4c664b0 Mon Sep 17 00:00:00 2001 From: Sergey Dolin Date: Tue, 29 Aug 2023 19:44:05 +0200 Subject: [PATCH 1/9] Update README.md with more sample --- README.md | 141 ++++++++++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 136 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index 525820ae5..652433a39 100644 --- a/README.md +++ b/README.md @@ -171,15 +171,146 @@ steps: - uses: actions/setup-go@v4 with: go-version: '1.17' - check-latest: true - cache-dependency-path: | - subdir/go.sum - tools/go.sum - # cache-dependency-path: "**/*.sum" + 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 From 57dc459658e35da19ce72ca4acc2fe7985beed80 Mon Sep 17 00:00:00 2001 From: Sergey Dolin Date: Wed, 30 Aug 2023 15:57:32 +0200 Subject: [PATCH 2/9] Add nesting --- README.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/README.md b/README.md index 652433a39..0ea50fbe6 100644 --- a/README.md +++ b/README.md @@ -163,7 +163,7 @@ in different subdirectories. The input supports glob patterns. If some problem that prevents success caching happens then the action issues the warning in the log and continues the execution of the pipeline. -**Caching in monorepos** +### Caching in monorepos ```yaml steps: @@ -175,7 +175,7 @@ steps: - run: go run hello.go ``` -**Caching in multirepos** +### Caching in multirepos `cache-dependency-path` input assepts glob patterns and multi-line values: ```yaml @@ -200,7 +200,7 @@ steps: - run: go run hello.go ``` -## Multi-target builds +### 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. @@ -220,7 +220,7 @@ steps: - run: go run hello.go ``` -## Invalidate cache when source code changes +### 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 @@ -245,7 +245,7 @@ of changes made in the repo. - run: go run hello.go ``` -## Caching with actions/cache +### 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. @@ -297,16 +297,16 @@ build: ``` -## Restore-only caches +### 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 +### 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 +### 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. From 1ac9d654af07606d4da12579126f1b9e0f806682 Mon Sep 17 00:00:00 2001 From: Sergey Dolin Date: Wed, 30 Aug 2023 16:15:18 +0200 Subject: [PATCH 3/9] Fix glob pattern use --- README.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index 0ea50fbe6..7e5ba9ca8 100644 --- a/README.md +++ b/README.md @@ -201,9 +201,7 @@ steps: ``` ### 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. +The 'cache-dependency-path' input doesn't limit itself to dependency lock files only. It can also be used with additional files that contain details about the build settings. By using this method, caches for builds created for various operating systems, architectures, etc. can be separated. ```yaml env: @@ -216,7 +214,9 @@ steps: - uses: actions/setup-go@v4 with: go-version: '1.17' - cache-dependency-path: go.sum /tmp/env + cache-dependency-path: | + go.sum + /tmp/env - run: go run hello.go ``` From ff99eca7af8723c53628926bd0f6612be6e40c4d Mon Sep 17 00:00:00 2001 From: Sergey Dolin Date: Wed, 30 Aug 2023 16:22:09 +0200 Subject: [PATCH 4/9] remove a sample with text file --- README.md | 11 ----------- 1 file changed, 11 deletions(-) diff --git a/README.md b/README.md index 7e5ba9ca8..fa586817a 100644 --- a/README.md +++ b/README.md @@ -234,17 +234,6 @@ including the source code files into `cache-dependency-path` input. - 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 From 9b4533e48459896ee8f92243c6ae211988cfd82c Mon Sep 17 00:00:00 2001 From: Sergey Dolin Date: Wed, 30 Aug 2023 16:30:41 +0200 Subject: [PATCH 5/9] add requested changes --- README.md | 20 ++++++++------------ 1 file changed, 8 insertions(+), 12 deletions(-) diff --git a/README.md b/README.md index fa586817a..a6071ed8c 100644 --- a/README.md +++ b/README.md @@ -209,7 +209,7 @@ env: GOARCH: ... steps: - - run: echo "$GOOS $GOARCH"> /tmp/env + - run: echo "$GOOS $GOARCH" > /tmp/env - uses: actions/setup-go@v4 with: @@ -235,16 +235,14 @@ including the source code files into `cache-dependency-path` input. ``` ### 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. +The caching capabilities of setup-go are limited to the simplest and most popular use cases. If fine-grained tuning of caching is required, it's recommended to disable the built-in caching and use [actions/cache](https://github.com/actions/cache). -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 +The example workflow below utilizes the `actions/cache` action and adds flexibility, for instance, it: + - allows to configure cache path + - allows to have different caches for rare changed dependencies and more often changed intermediate build files + - uses the `restore-key` input to restore the previous cache even if the current key cache has changed + - has different caches for the compiler's build outputs for different architectures + - has custom cache keys for parallel builds ```yaml build: @@ -269,8 +267,6 @@ build: 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 From d8ddd101cc8e0efbdb2fd84b8efa6eac045c6216 Mon Sep 17 00:00:00 2001 From: Sergey Dolin Date: Fri, 1 Sep 2023 10:27:52 +0200 Subject: [PATCH 6/9] remove tab --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index a6071ed8c..31b8f0083 100644 --- a/README.md +++ b/README.md @@ -216,7 +216,7 @@ steps: go-version: '1.17' cache-dependency-path: | go.sum - /tmp/env + /tmp/env - run: go run hello.go ``` From b91a04b1a7e34e7ec9f39571e024f39361dc1d0f Mon Sep 17 00:00:00 2001 From: Sergey Dolin Date: Sat, 4 Nov 2023 09:10:07 +0100 Subject: [PATCH 7/9] fix hashFile --- README.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index 31b8f0083..23c4b0ba5 100644 --- a/README.md +++ b/README.md @@ -209,14 +209,14 @@ env: GOARCH: ... steps: - - run: echo "$GOOS $GOARCH" > /tmp/env + - run: echo "$GOOS $GOARCH" > env.txt - uses: actions/setup-go@v4 with: go-version: '1.17' cache-dependency-path: | go.sum - /tmp/env + env.txt - run: go run hello.go ``` @@ -269,14 +269,14 @@ build: key: setup-go-deps-${{ runner.os }}-go-${{ hashFiles('go.sum go.mod') }} - name: - run: echo "$GOOS $GOARCH"> /tmp/env + run: echo "$GOOS $GOARCH"> env.txt - 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') }} + key: setup-go-build-${{ env.GOOS }}-${{ env.GOARCH }}-${{ runner.os }}-go-${{ hashFiles('**/*.go', 'env.txt') }} restore-keys: | setup-go-build-${{ env.GOOS }}-${{ env.GOARCH }} From b4a827d1162a3342e3ccf1dcb1461ce00bc00985 Mon Sep 17 00:00:00 2001 From: Sergey Dolin Date: Sat, 4 Nov 2023 09:15:21 +0100 Subject: [PATCH 8/9] fix hashFiles for modules dependencies --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 23c4b0ba5..7847a3caf 100644 --- a/README.md +++ b/README.md @@ -266,7 +266,7 @@ build: with: path: | ${{ env.cache }} - key: setup-go-deps-${{ runner.os }}-go-${{ hashFiles('go.sum go.mod') }} + key: setup-go-deps-${{ runner.os }}-go-${{ hashFiles('go.sum', 'go.mod') }} - name: run: echo "$GOOS $GOARCH"> env.txt From ffbd08bb260b2565b9c78e67da042c2cc65decce Mon Sep 17 00:00:00 2001 From: Sergey Dolin Date: Sat, 4 Nov 2023 09:30:38 +0100 Subject: [PATCH 9/9] fix restore-keys --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 7847a3caf..48660f151 100644 --- a/README.md +++ b/README.md @@ -278,7 +278,7 @@ build: ${{ env.modcache }} key: setup-go-build-${{ env.GOOS }}-${{ env.GOARCH }}-${{ runner.os }}-go-${{ hashFiles('**/*.go', 'env.txt') }} restore-keys: | - setup-go-build-${{ env.GOOS }}-${{ env.GOARCH }} + setup-go-build-${{ env.GOOS }}-${{ env.GOARCH }}-${{ runner.os }}-go ```