{"id":20236540,"url":"https://github.com/earthly/setup-ucacher","last_synced_at":"2026-02-27T11:40:46.655Z","repository":{"id":263406539,"uuid":"887976999","full_name":"earthly/setup-ucacher","owner":"earthly","description":"Installs ucacher (Earthly Universal Caching) in a GHA job","archived":false,"fork":false,"pushed_at":"2024-12-12T13:01:34.000Z","size":27936,"stargazers_count":99,"open_issues_count":7,"forks_count":3,"subscribers_count":4,"default_branch":"main","last_synced_at":"2025-06-18T08:51:18.952Z","etag":null,"topics":["cache","ptrace","syscall","universal"],"latest_commit_sha":null,"homepage":"","language":null,"has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/earthly.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2024-11-13T15:51:28.000Z","updated_at":"2025-05-26T18:20:12.000Z","dependencies_parsed_at":"2025-06-18T08:40:25.580Z","dependency_job_id":"36d948d4-e61e-44b1-adfe-44445378c3a0","html_url":"https://github.com/earthly/setup-ucacher","commit_stats":null,"previous_names":["earthly/setup-ucacher"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/earthly/setup-ucacher","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/earthly%2Fsetup-ucacher","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/earthly%2Fsetup-ucacher/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/earthly%2Fsetup-ucacher/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/earthly%2Fsetup-ucacher/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/earthly","download_url":"https://codeload.github.com/earthly/setup-ucacher/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/earthly%2Fsetup-ucacher/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29892297,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-27T09:48:51.284Z","status":"ssl_error","status_checked_at":"2026-02-27T09:48:43.992Z","response_time":57,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cache","ptrace","syscall","universal"],"created_at":"2024-11-14T08:21:34.621Z","updated_at":"2026-02-27T11:40:46.626Z","avatar_url":"https://github.com/earthly.png","language":null,"readme":"\n# setup-ucacher\n\nThis action installs Earthly `ucacher`.\n\n\u003e Read our new blog post about ucacher [here](https://earthly.dev/blog/ucacher/)\n\n## Universal caching with `ucacher`\n`ucacher` is a CLI tool that tracks which files are accessed by commands, skips unnecessary executions, and restores cached outputs when possible, resulting in significantly **reduced execution times**.\n\nIt brings: \n* **Faster feedback loops**\n   * Skips redundant tasks by detecting if specific files or commands are unaffected by changes.\n   * Reduces build times by caching outputs and avoiding unnecessary re-execution.\n* **Simplified caching and skipping**\n   * Automates caching and skipping with minimal setup.\n   * Eliminates the need for developers to manage cache keys, paths, or complex conditions.\n   * Removes the risk of human errors in configuration, reducing pipeline failures.\n* **Enhanced precision** (traditional caching mechanisms often rely on broad keys, which can invalidate the entire cache for small, unrelated changes)\n   * Tracks file dependencies at the command level using syscall instrumentation, enabling finer-grain caching.\n   * Only re-executes commands or jobs affected by actual changes.\n   * Prevents unnecessary invalidation and reruns, saving developer time and resources.\n* **Resource efficiency**\n   * Reduces resource consumption by skipping unaffected commands.\n   * Minimizes cloud infrastructure costs, making CI/CD pipelines more sustainable.\n   * Helps developers focus on coding rather than waiting for long-running jobs.\n* **Better developer experience**\n   * Offers out-of-the-box integration with tools like GitHub Actions, requiring minimal setup.\n   * Automatically manages input/output tracking, making caching and skipping invisible to the developer.\n   * Improves workflow reliability by ensuring that only the necessary jobs execute.\n* **Scalability for complex workflows**\n   * Handles complex scenarios like monorepos or task sharding with precision.\n   * Automatically adjusts caching and skipping based on changes in specific files or commands.\n   * Reduces unnecessary duplication in matrix jobs, saving time and resources across large teams.\n\n\n## Quick start\n### Install and configure `ucacher`\nAdd ucacher to your GitHub Actions workflow:\n\n```yaml\nsteps:\n- uses: earthly/setup-ucacher@main\n  ...\n```\n### Cache your commands\nTo cache a command, simply wrap it with `ucacher`:\n```yaml\nsteps:\n  ...\n  - run: ucacher \u003cyour_command\u003e\n```\n- First Run: The command runs as usual, with a slight overhead to upload output files.\n- Subsequent Runs: `ucacher` detects if the command’s output is unaffected by files changed. If so, it skips execution and restores the cached output files instantly.\n\n## How `ucacher` works\n`ucacher` utilizes `ptrace` to monitor files read (inputs) and written (outputs) by a command. When the command completes successfully, it uploads output files to persistent storage (e.g., GitHub Actions cache) along with some build metadata, in particular the hashes of all input files at the time they were read. \n\nOn subsequent runs, `ucacher` checks for matching initial conditions (input files content, arguments, environment variables, system architecture, etc.). If they match, it skips execution and restores the cached output files instead.\n\n## Example\nSuppose the following steps on a `node-js` project, that run the unit tests of the client and server application components:\n```yaml\nsteps:\n  ...\n- uses: earthly/setup-ucacher@main\n  ...\n  - run: ucacher yarn test --client\n  - run: ucacher yarn test --server\n```\nand the workflow already run for that branch. Now, if a change in `server-impl.js` is pushed, then:\n- `ucacher yarn test --client` would return the output from a compatible past execution right away, since that file is not used in the client tests. \n- `ucacher yarn test --server` would execute or return a cached result, depending on whether a compatible past execution is found (command already run for that file contents). \n\nThe reason why `ucacher` determines that this file isn’t used is indirect, not by explicitly checking it, but by finding a previous execution whose input file contents that match the current filesystem state. This indicates that this file (or potentially other files) is irrelevant to this specific command instance.\n\n## Customizing caching with ignored files and environment variables\nTo improve caching performance, certain files and environment variables can be ignored so that changes to them won’t prevent cache hits.\n\n### `.ucacherignore`\nPlace a `.ucacherignore` file in the root directory to define file patterns to ignore. Each line is a glob pattern that `ucacher` will use to filter out files.\n\n```plaintext\n.git/**/*\nnode_modules/**/*\n/tmp/**/*\n```\n\n### `.ucacherignore.env`\n\nDefine environment variable patterns to ignore in `.ucacherignore.env`:\n\n```plaintext\nGITHUB_TOKEN\nACTIONS_RUNTIME_TOKEN\nGITHUB_PATH\nGITHUB_OUTPUT\nGITHUB_ENV\n```\n\u003e Complete example here: [.ucacherignore.env](https://github.com/earthly/react/blob/uc-demo/.ucacherignore.env)\n\nThis prevents environment changes that don’t impact command output from invalidating the cache.\n\n### Comparison with actions/cache\n\n[actions/cache](https://github.com/actions/cache) is the official GitHub Action designed to cache dependencies and build outputs in GitHub Actions workflows. Here it is how they compare to each other:\n\n| Feature        | `actions/cache`               | `ucacher`                          |\n|----------------|-------------------------------|------------------------------------|\n| Output restore | File-based                    | Command-based                      |\n| Skipping       | Manual via `if` + `cache-hit` | Automatic                          |\n| Keying         | Manual, broad scope           | Automatic, only relevant files     |\n| Persistence    | GitHub cache                  | GitHub cache, S3, Minio (upcoming) |\n| Scope          | Step                          | Command                            |\n\n`ucacher` offers a more automated, precise, and efficient alternative to `actions/cache` in GitHub Actions by tracking file-level dependencies and automating caching and skipping at the command level. \n\nUnlike `actions/cache`, which requires manual setup with defined paths and keys, `ucacher` eliminates human errors and dynamically determines when commands should be skipped or re-executed based on actual file changes. \n\nThis results in finer-grain caching, better resource optimization, and significant time savings, especially in complex workflows like monorepos or matrix builds, where broad cache keys in `actions/cache` often lead to inefficiencies like unnecessarily invalidating unrelated steps, redundant execution of unchanged tasks and manual configuration errors.\n\n## Inputs\n### `github-token`\nThis token is used by `ucacher` to overwrite the Github Actions cache entry where the build metadata is stored. It requires **write** permissions for the `actions` scope in the GitHub REST API.\n\nIf omitted, the `GITHUB_TOKEN` of the job is used. This token should have enough permission by default. If that is not case, please refer to the [official GHA documentation](https://docs.github.com/en/actions/security-for-github-actions/security-guides/automatic-token-authentication#modifying-the-permissions-for-the-github_token) for guidance on modifying its permissions.  \n\n## Best practices\n1. **Split commands**: Divide large commands (e.g., `yarn test`) into smaller shards to maximize cache hit chances when only a subset of source files change.\n2. **Disable daemon modes**: If tools support daemon modes, consider disabling them for `ucacher` to track inputs and outputs accurately.\n3. **Use ignore files**: For maximum cache efficiency, use `.ucacherignore` and `.ucacherignore.env` to exclude irrelevant files and variables from tracking.\n\n## Limitations\n - **OS support**: Only Linux runners supported.\n - **Architecture support**: Currently only supports `amd64`.\n - **Inter-Process communication**: External processes not under the tree spawned by the command (like daemon or client-server setups) won’t have their file interactions tracked.\n\n## Licensing and privacy\n - **License**: `ucacher` is free to use; it may become open-source in the future.\n - **Data collection**: `ucacher` collects limited runtime metrics for maintenance, such as repository and organization names, commit author, and `ucacher`-specific errors. Source code or environment data is never collected.\n\n## Who is using `ucacher`?\n(in chronological order)\n\n 1. First spot available!\n 2. ...\n\n\u003e Using `ucacher`? Send a PR adding your repo at the end of the previous list\n\n## Feedback\nPlease give us feedback to keep improving it by opening an issue in this repo. In particular, we'd like to know:\n- Is it useful for you? Share some metrics with us\n- Is performance not as good as you’d like?\n- Is `ucacher` missing some file accesses?\n- Which feature would you like us to work next?\n- ...\n\nThanks!\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fearthly%2Fsetup-ucacher","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fearthly%2Fsetup-ucacher","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fearthly%2Fsetup-ucacher/lists"}