Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add documentation for advanced Go use cases. #416

Open
wants to merge 9 commits into
base: main
Choose a base branch
from
Open
Changes from 1 commit
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Next Next commit
Update README.md with more sample
dsame committed Aug 30, 2023
commit 3671db66cbd52001b473b82e63a6abeac4c664b0
141 changes: 136 additions & 5 deletions README.md
Original file line number Diff line number Diff line change
@@ -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 }}

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

should this be env.modcache and the next one be 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