Skip to content

Latest commit

 

History

History
172 lines (140 loc) · 6.2 KB

0000-caching-dependencies.md

File metadata and controls

172 lines (140 loc) · 6.2 KB
Raw

0. Caching dependencies

Date: 2022-04-13

Status: Accepted

Context

actions/setup-go is the one of the most popular action related to Golang in GitHub Actions. Many customers use it in conjunction with actions/cache to speed up dependency installation process.
See more examples on proper usage in actions/cache documentation.

Goals & Anti-Goals

Integration of caching functionality into actions/setup-go action will bring the following benefits for action users:

  • Decrease the entry threshold for using the cache for Go dependencies and simplify initial configuration
  • Simplify YAML pipelines because there will be no need for additional steps to enable caching
  • More users will use cache for Go so more customers will have fast builds!

We don't pursue the goal to provide wide customization of caching in scope of actions/setup-go action. The purpose of this integration is covering ~90% of basic use-cases. If user needs flexible customization, we should advice them to use actions/cache directly.

Decision

  • Add cache input parameter to actions/setup-go. For now, input will accept the following values:
    • true - enable caching for go dependencies
    • false- disable caching for go dependencies. This value will be set as default value
  • Cache feature will be disabled by default to make sure that we don't break existing customers. We will consider enabling cache by default in next major releases
  • Action will try to search a go.sum files in the repository and throw error in the scenario that it was not found
  • The hash of found file will be used as cache key (the same approach like actions/cache recommends)
  • The following key cache will be used ${{ runner.os }}-go${{ go-version }}-${{ hashFiles('<go.sum-path>') }}
  • Action will cache global cache from the go env GOMODCACHE and go env GOCACHE commands.
  • Add a cache-dependency-path input parameter to actions/setup-go. The new input will accept an array or regex of dependency files. The field will accept a path (relative to the repository root) to dependency files. If the provided path contains wildcards, the action will search all matching files and calculate a common hash like the ${{ hashFiles('**/go.sum') }} YAML construction does.

Example of real use-cases

With cache

steps:
- uses: actions/checkout@v3
- uses: actions/setup-go@v3
  with:
    go-version: '18'
    cache: true

With cache-dependency-path

steps:
- uses: actions/checkout@v3
- uses: actions/setup-go@v3
 with:
   go-version: '18'
   cache: true
   cache-dependency-path: **/go.sum
steps:
- uses: actions/checkout@v3
- uses: actions/setup-go@v3
 with:
   go-version: '18'
   cache: true
   cache-dependency-path: |
       **/go.sum
       **/go.mod
steps:
- uses: actions/checkout@v3
- uses: actions/setup-go@v3
 with:
   go-version: '18'
   cache: true
   cache-dependency-path: **/go.sum

Multi-target builds

env:
  GOOS: ...
  GOARCH: ...

steps:
  - run: echo "$GOOS $GOARCH"> /tmp/env

  - uses: actions/setup-go@v4
    with:
      cache-dependency-path: go.sum /tmp/env

Invalidate cache if source code changes

- uses: actions/setup-go@v4
  with:
    go-version: '1.20'
    cache-dependency-path: go.sum **/*.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 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
  • have different caches intermediate build files of different architectures
  • have custom cache key for parallel builds
build:
  env:
   GOOS: ...
   GOARCH: ...

  steps:
  - uses: actions/setup-go@v4
    with:
      go-version: "1.20.x"
      cache: false

  - name: Get Go cached paths
    id: find-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 should be used in this case.

Include or exclude cached paths

This advanced use case requires the use of actions/cache

Generate different caches

This advanced use case assumes manual definition of cache key and requires the use of actions/cache

Parallel builds

To avoid race conditions during the parallel builds they should either generate their own caches, or create the cache for only one build and restore that cache in the other builds.

Release process

As soon as functionality is implemented, we will release minor update of action. No need to bump major version since there are no breaking changes for existing users. After that, we will update starter-workflows