External/pmg
1
0
Fork 0
mirror of https://github.com/safedep/pmg.git synced 2026-08-03 07:24:09 +02:00
Code Issues Packages Projects Releases Wiki Activity

feat: add GitHub Action for one-step PMG setup in CI (#263)

Browse Source 
* feat: add GitHub Action for one-step PMG setup in CI

Composite action at repo root that downloads PMG (with SHA-256 verification
against the upstream checksums.txt), runs `pmg setup install`, and wires
shims onto $GITHUB_PATH so subsequent `npm install` / `pip install` calls
are transparently analyzed.

Defaults are conservative: malware blocking + dependency cooldown + proxy
mode (matching PMG's own defaults). Sandbox is opt-in because enabling
Landlock/Bubblewrap on ubuntu-latest requires relaxing AppArmor
user-namespace restrictions.

Cloud sync uses the documented SAFEDEP_API_KEY / SAFEDEP_TENANT_ID env-var
fallback so we skip the keychain codepath that has no usable backend in
headless CI. When cloud is enabled and no endpoint-id is supplied, the
action sets PMG_CLOUD_ENDPOINT_ID=github-actions/${GITHUB_REPOSITORY} so
events aggregate per repository instead of per ephemeral runner hostname.

Closes #248.

https://claude.ai/code/session_01ARb8ZiBiJjvhWjchBXraAh

* fix(action): drop github.repository template from input description

Action manifest validation rejected the action.yml because the endpoint-id
input description contained ${{ github.repository }} — template expressions
aren't evaluated in input description text and trip the validator with
"Unrecognized named-value: 'github'". This caused every job using uses: ./
to fail before any step ran.

Also switch the config-file e2e job to verify the staged file directly
instead of calling `pmg config get`, which is not in the v0.13.0 release
that "latest" resolves to today.

https://claude.ai/code/session_01ARb8ZiBiJjvhWjchBXraAh

* fix(action): address review comments on PR #263

- Drop opinionated defaults on PMG_* toggle inputs. All defaults are now
  empty strings, and the action only exports PMG_* env vars when the
  caller explicitly sets the input. Without this, defaults like
  PMG_PARANOID=false silently shadowed config-file overrides because env
  vars beat config.yml in Viper precedence.
- Verify cached PMG against upstream checksums.txt on every cache hit.
  The cached tarball is stored alongside the binary and re-hashed against
  the freshly-fetched checksums.txt; on drift, the cache entry is evicted
  and re-downloaded.
- Export PMG_* env vars BEFORE running `pmg setup install` so settings
  like disable-telemetry actually apply during setup, not just to
  subsequent package-manager calls.
- Add `|| true` to the grep that extracts the expected checksum so
  set -e doesn't kill the script before the friendly error message fires
  when no checksum entry is found.
- Pin third-party actions (actions/checkout, actions/setup-node) to
  commit SHAs to match the repo's supply-chain hardening convention.
- Fix the malicious-package E2E test capturing tee's exit code instead
  of npm's; redirect to a file and check the actual command exit code.
- Add an E2E job that asserts PMG_PARANOID is unset when only
  config-file is provided — regression guard for the precedence fix.

https://claude.ai/code/session_01ARb8ZiBiJjvhWjchBXraAh

* ci(action-e2e): scope sandbox tests to action setup, not PMG runtime

The landlock job was running `npm install express` with no explicit
sandbox profile and the default profile blocks something npm needs
(PMG's own e2e uses `--sandbox-profile npm-restrictive` to make this
viable). Bubblewrap happened to pass, but verifying the default sandbox
profile is permissive enough for arbitrary package installs is PMG's
e2e responsibility — this workflow's job is to assert the action wires
sandbox config correctly.

Switch both drivers to a matrix and verify only what the action owns:
PMG_SANDBOX_* env vars propagated, pmg binary runs, bwrap is installed
when requested, AppArmor user-ns restriction relaxed.

https://claude.ai/code/session_01ARb8ZiBiJjvhWjchBXraAh

* ci(action-e2e): bump setup-node to 24

Node 20 reached end-of-life and setup-node now warns on it. Match the
version pinned by publish-npm.yml (the repo's newest workflow). Updated
the README and docs/github-action.md quick-start examples to match.

https://claude.ai/code/session_01ARb8ZiBiJjvhWjchBXraAh

---------

Co-authored-by: Claude <noreply@anthropic.com>
This commit is contained in:
Abhisek Datta
2026-05-18 00:44:06 +05:30
committed by GitHub
co-authored by Claude
parent c78287e5a0
commit 46cc70db53
4 changed files with 640 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/github-action.md
+161
View File
@@ -0,0 +1,161 @@
# PMG GitHub Action
Install PMG in a Linux GitHub Actions runner and transparently wrap every
subsequent `npm install`, `pip install`, `poetry add`, etc. so malicious
packages are blocked before they execute.
```yaml
- uses: safedep/pmg@v1
```
That's it. Out of the box you get:
- malware blocking against [SafeDep's real-time threat intelligence](https://docs.safedep.io/cloud/malware-analysis)
- a 5-day dependency cooldown (blocks freshly-published versions)
- proxy-based interception of npm/pip/pnpm/yarn/bun/poetry/uv/npx/pnpx
## Quick start
```yaml
jobs:
build:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: 24
- uses: safedep/pmg@v1
- run: npm ci
```
**Order matters.** Put `safedep/pmg` **after** `setup-node` / `setup-python`
/ etc. Each step that writes to `GITHUB_PATH` prepends to `PATH`, and PMG
needs its shims (`$HOME/.pmg/bin/{npm,pip,...}`) to land in front of the
real toolchains.
## Inputs
All toggle inputs default to empty. When empty, the action emits no
`PMG_*` env var for that key and PMG's own defaults apply — so a YAML
loaded via `config-file` is never silently shadowed. Set an input
explicitly to override.
| Input | Effect when set | PMG default if empty |
|---|---|---|
| `version` | PMG release tag (e.g. `v0.42.0`) or `latest` | `latest` |
| `api-key` | SafeDep Cloud API key. Set together with `tenant-id`; mask with a secret | unset (cloud sync disabled) |
| `tenant-id` | SafeDep Cloud tenant ID | unset |
| `endpoint-id` | Reported to SafeDep Cloud as the "machine" identifier | `github-actions/<owner>/<repo>` when cloud is enabled |
| `paranoid` | `PMG_PARANOID` | `false` |
| `cooldown-enabled` | `PMG_DEPENDENCY_COOLDOWN_ENABLED` | `true` |
| `cooldown-days` | `PMG_DEPENDENCY_COOLDOWN_DAYS` | `5` |
| `proxy-mode` | `PMG_PROXY_ENABLED`. Set `false` for guard-based analysis | `true` |
| `sandbox` | `PMG_SANDBOX_ENABLED`. Also relaxes AppArmor user-ns restrictions on the runner | `false` |
| `sandbox-driver` | `PMG_SANDBOX_DRIVER` — `landlock` or `bubblewrap` | `landlock` when sandbox is enabled |
| `verbosity` | `PMG_VERBOSITY` — `silent`, `normal`, or `verbose` | `normal` |
| `disable-telemetry` | `PMG_DISABLE_TELEMETRY` | `false` |
| `skip-event-logging` | `PMG_SKIP_EVENT_LOGGING` | `false` |
| `config-file` | Path to a YAML file in the repo. Copied to PMG's config dir before setup so you can override any config key | unset |
| `cache` | Reuse a previously-extracted PMG binary from `$RUNNER_TOOL_CACHE`. On cache hit, the cached tarball is re-verified against `checksums.txt` fetched from upstream every run | `false` (fresh download per run) |
## Outputs
| Output | Description |
|---|---|
| `version` | The resolved PMG version that was installed. |
| `bin-dir` | Directory containing the `pmg` binary on this runner. |
## Recipes
### Send audit events to SafeDep Cloud
```yaml
- uses: safedep/pmg@v1
with:
api-key: ${{ secrets.SAFEDEP_API_KEY }}
tenant-id: ${{ secrets.SAFEDEP_TENANT_ID }}
- run: npm ci
# At the end of the job, flush events to SafeDep Cloud.
- run: pmg cloud sync --timeout 60s
if: always()
```
Why the explicit sync step? Composite actions don't have a clean post-step
hook today. A single trailing step (`if: always()`) keeps everything
visible in your workflow file.
The `endpoint-id` defaults to `github-actions/${{ github.repository }}` so
every workflow on the same repo appears as one endpoint in the SafeDep
Cloud UI. Override it for per-environment splits:
```yaml
- uses: safedep/pmg@v1
with:
api-key: ${{ secrets.SAFEDEP_API_KEY }}
tenant-id: ${{ secrets.SAFEDEP_TENANT_ID }}
endpoint-id: github-actions/${{ github.repository }}/prod
```
### Custom configuration via `config-file`
```yaml
# .github/pmg.yml — pinned in the repo
paranoid: true
dependency_cooldown:
enabled: true
days: 14
trusted_packages:
- purl: pkg:npm/@my-org/internal-pkg
reason: "Internal package, signed by build pipeline"
```
```yaml
- uses: safedep/pmg@v1
with:
config-file: .github/pmg.yml
```
The file is copied into `~/.config/safedep/pmg/config.yml` before
`pmg setup install` runs. PMG merges any missing template keys into it, so
you only need to specify what you want to override.
### Sandbox mode
```yaml
- uses: safedep/pmg@v1
with:
sandbox: true
sandbox-driver: landlock # or "bubblewrap"
- run: npm ci
```
The action will `systemctl stop apparmor` and clear
`kernel.apparmor_restrict_unprivileged_userns` so unprivileged user
namespaces work. This mutates the runner — only enable when you actually
need install-script containment.
### Setting arbitrary `PMG_*` env vars
Any PMG config key can be overridden via a `PMG_*` env var without an
action input. Set it on the job or the install step:
```yaml
- uses: safedep/pmg@v1
- run: npm ci
env:
PMG_TRANSITIVE_DEPTH: 10
```
See [docs/config.md](./config.md) for the full mapping.
## Platform support
| Runner | Supported |
|---|---|
| `ubuntu-latest`, `ubuntu-24.04`, `ubuntu-22.04` (x86_64 + arm64) | Yes |
| `macos-*` | No (fail fast) |
| `windows-*` | No (fail fast) |
macOS and Windows runners are tracked in
[issue #248](https://github.com/safedep/pmg/issues/248).