mirror of
https://github.com/awalsh128/cache-apt-pkgs-action.git
synced 2026-11-13 13:26:34 +00:00
Refresh README for current v1 state (#226)
Rebased onto master without #224, which moved to v2 (#230). The Errors section now lists only the input validation exit codes v1 has, with a note that some resolution and install failures aren't caught in v1. Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
Andrew Walsh
GitHub
parent
75f34b28cb
commit
32eff9e8b1
110
README.md
110
README.md
|
|
@ -1,16 +1,20 @@
|
|||
# cache-apt-pkgs-action
|
||||
<img src="https://raw.githubusercontent.com/awalsh128/cache-apt-pkgs-action/main-2/logo.png" alt="Cache APT Packages logo" height="80" align="center"> <b>Cache APT Packages Action</b>
|
||||
|
||||
[](https://github.com/awalsh128/fluentcpp/blob/master/LICENSE)
|
||||
[](https://github.com/awalsh128/cache-apt-pkgs-action/actions/workflows/action-tests.yml?query=branch%3Amaster)
|
||||
[](https://github.com/awalsh128/cache-apt-pkgs-action/actions/workflows/action-tests.yml?query=branch%3Adev)
|
||||
[](https://github.com/awalsh128/cache-apt-pkgs-action/blob/master/LICENSE)
|
||||
[](https://github.com/awalsh128/cache-apt-pkgs-action/actions/workflows/action-tests.yml?query=branch%3Amaster)
|
||||
[](https://github.com/awalsh128/cache-apt-pkgs-action/actions/workflows/action-tests.yml?query=branch%3Adev)
|
||||
[](https://github.com/awalsh128/cache-apt-pkgs-action/releases)
|
||||
|
||||
This action allows caching of Advanced Package Tool (APT) package dependencies to improve workflow execution time instead of installing the packages on every run.
|
||||
|
||||
> [!IMPORTANT]
|
||||
> Version 1 will be in maintenance mode. Due to recently instability in the releases and to create consistent reliability, I am going to lock v1. Version 2 beta will be coming soon to have better testing, and less reliability on Bash script where it has triggered more than one major break.
|
||||
> Version 1 is in maintenance mode. Recent releases have been unstable, so v1 is locked to bug fixes and reliability work. Version 2 is in development on the [`main-2`](https://github.com/awalsh128/cache-apt-pkgs-action/tree/main-2) branch. It is written in TypeScript, has better test coverage and relies much less on Bash scripts, which have caused more than one major break.
|
||||
|
||||
> [!IMPORTANT]
|
||||
> Looking for co-maintainers to help review changes, and investigate issues. I haven't had as much time to stay on top of this action as I would like to and want to make sure it is still responsive and reliable for the community. If you are interested, please reach out.
|
||||
> [!TIP]
|
||||
> If you find this project useful, please consider supporting it [as a sponsor and show some ❤️ for open source maintainers](https://github.com/sponsors/awalsh128).
|
||||
|
||||
> [!NOTE]
|
||||
> Looking for co-maintainers to help review changes and investigate issues. I haven't had as much time to stay on top of this action as I would like, and I want to make sure it stays responsive and reliable for the community. If you are interested, please reach out.
|
||||
|
||||
## Documentation
|
||||
|
||||
|
|
@ -28,19 +32,21 @@ There are two kinds of version labels you can use.
|
|||
|
||||
- `@v#` - Major only will give you the latest release for that major version only (e.g. `v1`).
|
||||
- Branch
|
||||
- `@master` - Most recent manual and automated tested code. Possibly unstable since it is pre-release.
|
||||
- `@staging` - Most recent automated tested code and can sometimes contain experimental features. Is pulled from dev stable code.
|
||||
- `@dev` - Very unstable and contains experimental features. Automated testing may not show breaks since CI is also updated based on code in dev.
|
||||
- `@master` - Most recent manual and automated tested code. Possibly unstable since it is pre-release (publishes as `1.x.x`).
|
||||
- `@dev` - Very unstable and contains experimental features.
|
||||
- `@main-2` - Version 2 in development. Not released yet; do not use in production workflows.
|
||||
|
||||
Please note that the `latest` symbol has been deprecated and will no longer be updated. Actions should be pinned to a well known version instead.
|
||||
The `latest` tag is deprecated and will no longer be updated. Pin to a major version (e.g. `@v1`), a release tag (e.g. `@v1.6.3`) or a full commit SHA instead.
|
||||
|
||||
### Inputs
|
||||
|
||||
- `packages` - Space delimited list of packages to install.
|
||||
- `packages` - Space delimited list of packages to install. A version can optionally be given using APT syntax `<name>=<version>` (e.g. `xdot=1.2-2`).
|
||||
- `version` - Version of cache to load. Each version will have its own cache. Note, all characters except spaces are allowed.
|
||||
- `execute_install_scripts` - Execute Debian package pre and post install script upon restore. See [Caveats / Non-file Dependencies](#non-file-dependencies) for more information.
|
||||
- `empty_packages_behavior` - Desired behavior when the given `packages` is empty. `'error'` (default), `'warn'` or `'ignore'`.
|
||||
- `add-repository` - Space delimited list of repositories to add via `apt-add-repository` before installing packages. Supports PPA (e.g., `ppa:user/repo`) and other repository formats.
|
||||
- `debug` - Enable debug logging and upload the action logs as a workflow artifact. Minor performance penalty. Default `false`.
|
||||
- `refresh` - **Obsolete.** Not used by the action; use `version` instead.
|
||||
|
||||
### Outputs
|
||||
|
||||
|
|
@ -48,6 +54,75 @@ Please note that the `latest` symbol has been deprecated and will no longer be u
|
|||
- `package-version-list` - The main requested packages and versions that are installed. Represented as a comma delimited list with equals delimit on the package version (i.e. \<package1>=<version1\>,\<package2>=\<version2>,...).
|
||||
- `all-package-version-list` - All the pulled in packages and versions, including dependencies, that are installed. Represented as a comma delimited list with equals delimit on the package version (i.e. \<package1>=<version1\>,\<package2>=\<version2>,...).
|
||||
|
||||
### Errors
|
||||
|
||||
The action checks its inputs before doing anything else, and fails the step with its own exit code for each problem so you can tell them apart in the logs.
|
||||
|
||||
| Code | Cause |
|
||||
| ---- | -------------------------------------------------------------------------- |
|
||||
| 1 | `debug` is not `true` or `false`. |
|
||||
| 2 | `version` contains spaces. |
|
||||
| 3 | `packages` is empty and `empty_packages_behavior` is `error`. |
|
||||
| 4 | `execute_install_scripts` is not `true` or `false`. |
|
||||
| 6 | A value in `add-repository` contains invalid characters. |
|
||||
|
||||
> [!NOTE]
|
||||
> v1 doesn't catch every package resolution or install failure, so the action can report success after an incomplete install. Failing on these errors is planned for v2 (see [#230](https://github.com/awalsh128/cache-apt-pkgs-action/issues/230)).
|
||||
|
||||
### Security Compliance
|
||||
|
||||
This is a composite action. It runs Bash scripts and a small Go helper (`apt_query`), committed as prebuilt binaries for x86 and arm64, on the runner. It uses `sudo` to install packages. Consumers don't need to install anything else.
|
||||
|
||||
For workflows with stricter compliance requirements, the main security characteristics are:
|
||||
|
||||
- `packages` should be treated as an allowlisted input in your workflow. Prefer explicit package names and versions where reproducibility matters.
|
||||
- `version` can be used as a cache namespace so you can intentionally rotate caches when package policy or runner baselines change.
|
||||
- `empty_packages_behavior` can be left at the default `error` to fail closed when an expected package list is missing.
|
||||
- `execute_install_scripts` is disabled by default. Enable it only when required, because Debian maintainer scripts run arbitrary package-provided shell logic during restore.
|
||||
- `debug` is disabled by default. When enabled, logs are uploaded as a workflow artifact. Review them before sharing outside your organization.
|
||||
- `add-repository` adds third-party APT sources to the runner. Only add repositories you trust.
|
||||
- On a cache miss, if `apt-fast` isn't already on the runner, the action downloads and runs its install script from the [apt-fast](https://github.com/ilikenwf/apt-fast) repository.
|
||||
|
||||
#### Features
|
||||
|
||||
Security-relevant action features:
|
||||
|
||||
- Package inputs are normalized and sorted before cache lookup, which reduces accidental cache divergence from ordering or duplicate whitespace in the package list.
|
||||
- Unpinned package names are resolved to concrete package versions before the cache key is generated, which improves traceability of what was actually cached for a run.
|
||||
- Cache keys are derived from the normalized package set, the user-provided `version`, the added repositories and the runner architecture, which helps isolate caches across package changes and incompatible platforms.
|
||||
- The action rejects invalid boolean inputs, `version` values containing spaces and repository values with invalid characters.
|
||||
- Actions that this action depends on (`actions/cache`, `actions/upload-artifact`) are pinned to full commit SHAs.
|
||||
- The `package-version-list` and `all-package-version-list` outputs can be captured by downstream workflow steps for audit logs, attestation inputs, or compliance reporting.
|
||||
|
||||
#### Usage Recommendations
|
||||
|
||||
For GitHub Actions workflow hardening, prefer the following controls around this action:
|
||||
|
||||
- Pin this action to a release tag you trust, or to a full commit SHA for stricter supply chain control.
|
||||
- Use the minimum required workflow `permissions` instead of broad defaults.
|
||||
- Run on GitHub-hosted or otherwise trusted runners with controlled APT sources.
|
||||
- Limit who can modify workflow files and package lists through branch protection and pull request review.
|
||||
- Review whether cached APT contents are acceptable for your repository's cache retention policy and data handling requirements.
|
||||
|
||||
Example hardened usage:
|
||||
|
||||
```yaml
|
||||
permissions:
|
||||
contents: read
|
||||
|
||||
jobs:
|
||||
build:
|
||||
runs-on: ubuntu-24.04
|
||||
steps:
|
||||
- uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
|
||||
- uses: awalsh128/cache-apt-pkgs-action@v1.6.3
|
||||
with:
|
||||
packages: curl=8.5.0-2ubuntu10.6 jq=1.7.1-3build1
|
||||
version: ubuntu-24.04-v1
|
||||
empty_packages_behavior: error
|
||||
execute_install_scripts: false
|
||||
```
|
||||
|
||||
### Cache scopes
|
||||
|
||||
The cache key is built from the `packages`, `version` and `add-repository` inputs, plus the runner's CPU architecture. The branch name is not part of the key.
|
||||
|
|
@ -76,7 +151,7 @@ jobs:
|
|||
|
||||
- name: Build
|
||||
run: |
|
||||
cmake -B ${{github.workspace}}/build -DCMAKE_BUILD_TYPE=${{env.BUILD_TYPE}}
|
||||
cmake -B ${{github.workspace}}/build -DCMAKE_BUILD_TYPE=${{env.BUILD_TYPE}}
|
||||
cmake --build ${{github.workspace}}/build --config ${{env.BUILD_TYPE}}
|
||||
|
||||
- name: Deploy
|
||||
|
|
@ -87,7 +162,6 @@ jobs:
|
|||
```
|
||||
|
||||
```yaml
|
||||
|
||||
---
|
||||
install_doxygen_deps:
|
||||
runs-on: ubuntu-latest
|
||||
|
|
@ -138,7 +212,7 @@ This action is based on the principle that most packages can be cached as a file
|
|||
- Pre and post installation scripts needs to be ran from `/var/lib/dpkg/info/{package name}.[preinst, postinst]`.
|
||||
- The Debian package database needs to be queried for scripts above (i.e. `dpkg-query`).
|
||||
|
||||
The `execute_install_scripts` argument can be used to attempt to execute the install scripts but they are no guaranteed to resolve the issue.
|
||||
The `execute_install_scripts` argument can be used to attempt to execute the install scripts but they are not guaranteed to resolve the issue.
|
||||
|
||||
```yaml
|
||||
- uses: awalsh128/cache-apt-pkgs-action@v1
|
||||
|
|
@ -159,6 +233,10 @@ Please reach out if you have found a workaround for your scenario and it can be
|
|||
|
||||
For more context and information see [issue #57](https://github.com/awalsh128/cache-apt-pkgs-action/issues/57#issuecomment-1321024283) which contains the investigation and conclusion.
|
||||
|
||||
### Virtual Packages
|
||||
|
||||
Virtual packages are resolved to a concrete package that provides them. A virtual package with no provider (e.g. `python` on Ubuntu 22.04) can't be resolved. Use the concrete package name instead (e.g. `python3`).
|
||||
|
||||
### Cache Limits
|
||||
|
||||
A repository can have up to 5GB of caches. Once the 5GB limit is reached, older caches will be evicted based on when the cache was last accessed. Caches that are not accessed within the last week will also be evicted. To get more information on how to access and manage your actions's caches, see [GitHub Actions / Using workflows / Cache dependencies](https://docs.github.com/en/actions/using-workflows/caching-dependencies-to-speed-up-workflows#viewing-cache-entries).
|
||||
A repository can have up to 10GB of caches. Once the limit is reached, older caches will be evicted based on when the cache was last accessed. Caches that are not accessed within the last week will also be evicted. To get more information on how to access and manage your actions's caches, see [GitHub Actions / Using workflows / Cache dependencies](https://docs.github.com/en/actions/using-workflows/caching-dependencies-to-speed-up-workflows#viewing-cache-entries).
|
||||
|
|
|
|||
Loading…
Reference in a new issue