mirror of
https://github.com/actions/cache.git
synced 2025-11-04 15:48:39 +08:00
139 lines
4.0 KiB
Markdown
139 lines
4.0 KiB
Markdown
## Usage
|
|
|
|
### Pre-requisites
|
|
Create a workflow `.yml` file in your repositories `.github/workflows` directory. An [example workflow](#example-workflow) is available below. For more information, reference the GitHub Help Documentation for [Creating a workflow file](https://help.github.com/en/articles/configuring-a-workflow#creating-a-workflow-file).
|
|
|
|
### Inputs
|
|
|
|
* `path` - A list of files, directories, and wildcard patterns to cache and restore. See [`@actions/glob`](https://github.com/actions/toolkit/tree/main/packages/glob) for supported patterns.
|
|
* `key` - An explicit key for restoring and saving the cache
|
|
* `restore-keys` - An ordered list of keys to use for restoring the cache if no cache hit occurred for key
|
|
* `bucket` - aws s3 bucket
|
|
* `access-key-id` - aws access key id *OPTIONAL*
|
|
* `secret-access-key` - aws secret access key *OPTIONAL*
|
|
|
|
### Outputs
|
|
|
|
* `cache-hit` - A boolean value to indicate an exact match was found for the key
|
|
|
|
> See [Skipping steps based on cache-hit](#Skipping-steps-based-on-cache-hit) for info on using this output
|
|
### Cache scopes
|
|
The cache is scoped to the key and branch. The default branch cache is available to other branches.
|
|
|
|
See [Matching a cache key](https://help.github.com/en/actions/configuring-and-managing-workflows/caching-dependencies-to-speed-up-workflows#matching-a-cache-key) for more info.
|
|
|
|
### Example workflow
|
|
|
|
```yaml
|
|
name: Caching Node Modules
|
|
on: push
|
|
jobs:
|
|
build-with-cache:
|
|
name: NPM Install with Cache
|
|
runs-on: ubuntu-latest
|
|
steps:
|
|
- name: Checkout Repo
|
|
uses: actions/checkout@v2
|
|
- uses: hipcamp/cache@v0.13.0
|
|
id: node-cache
|
|
with:
|
|
bucket: [your cache bucket]
|
|
path: node_modules
|
|
key: node-${{ hashFiles('**/package-lock.json') }}
|
|
restore-keys: |
|
|
node-
|
|
- run: npm install
|
|
```
|
|
|
|
## Skipping steps based on cache-hit
|
|
|
|
Using the `cache-hit` output, subsequent steps (such as install or build) can be skipped when a cache hit occurs on the key.
|
|
|
|
Example:
|
|
```yaml
|
|
steps:
|
|
- uses: actions/checkout@v2
|
|
- uses: actions/cache@v2
|
|
id: cache
|
|
with:
|
|
path: path/to/dependencies
|
|
key: ${{ runner.os }}-${{ hashFiles('**/lockfiles') }}
|
|
- name: Install Dependencies
|
|
if: steps.cache.outputs.cache-hit != 'true'
|
|
run: /install.sh
|
|
```
|
|
|
|
> Note: The `id` defined in `actions/cache` must match the `id` in the `if` statement (i.e. `steps.[ID].outputs.cache-hit`)
|
|
|
|
## How to Contribute
|
|
|
|
> First, you'll need to have a reasonably modern version of `node` handy. This won't work with versions older than 9, for instance.
|
|
|
|
Install the dependencies
|
|
```bash
|
|
$ npm install
|
|
```
|
|
|
|
Build the typescript and package it for distribution
|
|
```bash
|
|
$ npm run build && npm run package
|
|
```
|
|
|
|
Run the tests :heavy_check_mark:
|
|
```bash
|
|
$ npm test
|
|
|
|
PASS ./index.test.js
|
|
✓ throws invalid number (3ms)
|
|
✓ wait 500 ms (504ms)
|
|
✓ test runs (95ms)
|
|
|
|
...
|
|
```
|
|
|
|
## Change action.yml
|
|
|
|
The action.yml contains defines the inputs and output for your action.
|
|
|
|
Update the action.yml with your name, description, inputs and outputs for your action.
|
|
|
|
See the [documentation](https://help.github.com/en/articles/metadata-syntax-for-github-actions)
|
|
|
|
## Change the Code
|
|
|
|
Most toolkit and CI/CD operations involve async operations so the action is run in an async function.
|
|
|
|
```javascript
|
|
import * as core from '@actions/core';
|
|
...
|
|
|
|
async function run() {
|
|
try {
|
|
...
|
|
}
|
|
catch (error) {
|
|
core.setFailed(error.message);
|
|
}
|
|
}
|
|
|
|
run()
|
|
```
|
|
|
|
See the [toolkit documentation](https://github.com/actions/toolkit/blob/master/README.md#packages) for the various packages.
|
|
|
|
## Publish to a Distribution Branch
|
|
|
|
Actions are run from GitHub repos so we will checkin the packed dist folder.
|
|
|
|
```bash
|
|
$ npm run all
|
|
$ git add -A
|
|
$ git commit -m "your commit message"
|
|
$ git tag v[version from package.json]
|
|
$ git push origin v[version from package.json]
|
|
```
|
|
|
|
Your action is now published! :rocket:
|
|
|
|
See the [versioning documentation](https://github.com/actions/toolkit/blob/master/docs/action-versioning.md)
|