You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: .github/ACT.md
+14-14Lines changed: 14 additions & 14 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -4,35 +4,35 @@
4
4
5
5
**act** is a CLI that runs **GitHub Actions workflows on your computer** instead of on GitHub. It starts **Docker** containers that behave like GitHub’s `ubuntu-latest` runners, checks out your repo (or copies the working tree), and runs the same `run:` steps your YAML defines.
6
6
7
-
You use it to **catch CI failures before you push**—for example broken `plugin.json`, bad SKILL frontmatter, or failed skill checks.
7
+
You use it to **catch CI failures before you push**-for example broken `plugin.json`, bad SKILL frontmatter, or failed skill checks.
8
8
9
9
## How it works (mental model)
10
10
11
-
1.**Event**— You tell act what happened, e.g. `push` or `pull_request`. Many of our workflows are written for `on: push` / `pull_request`, so `act push` is the usual choice.
12
-
2.**Workflow file**— You pass **which YAML** to run with `-W .github/workflows/<file>.yml`. act does **not** read `on: paths:` the same way GitHub does; if you pass a file, act runs that workflow.
13
-
3.**Jobs**— act lists jobs with `act -l -W …`, then runs them in Docker when you use `act push -W …`.
14
-
4.**Checkout**—`actions/checkout` inside the container gets your project files (warnings like `unable to get git ref` are common until you have at least one git commit; the tree is still copied).
11
+
1.**Event**- You tell act what happened, e.g. `push` or `pull_request`. Many of our workflows are written for `on: push` / `pull_request`, so `act push` is the usual choice.
12
+
2.**Workflow file**- You pass **which YAML** to run with `-W .github/workflows/<file>.yml`. act does **not** read `on: paths:` the same way GitHub does; if you pass a file, act runs that workflow.
13
+
3.**Jobs**- act lists jobs with `act -l -W …`, then runs them in Docker when you use `act push -W …`.
14
+
4.**Checkout**-`actions/checkout` inside the container gets your project files (warnings like `unable to get git ref` are common until you have at least one git commit; the tree is still copied).
15
15
16
16
Nothing is sent to GitHub when you run act; it is **fully local** (except pulling Docker images the first time).
17
17
18
18
## Prerequisites
19
19
20
20
1.**Docker** running (`docker info` should succeed).
21
-
2.**act** installed —[releases](https://github.com/nektos/act/releases) or e.g. `brew install act`. Use **act ≥ 0.2.86** when possible (security fixes).
21
+
2.**act** installed -[releases](https://github.com/nektos/act/releases) or e.g. `brew install act`. Use **act ≥ 0.2.86** when possible (security fixes).
22
22
23
23
## Run this repo’s CI locally (copy-paste)
24
24
25
25
From the **repository root**:
26
26
27
-
**Recommended — all workflows (same as `task act`):**
27
+
**Recommended - all workflows (same as `task act`):**
28
28
29
29
```bash
30
30
./scripts/act-all.sh
31
31
```
32
32
33
-
That script lists and runs **validate-plugin** and **test-skills** with `act push` (these **must** succeed — the script exits non-zero if either fails). It then runs **semantic-pull-request** (`act pull_request` + [`.github/act/event-pull_request.json`](act/event-pull_request.json)) and **release-please** (`act push`) as **extra smoke tests**. Those two workflows call the **GitHub REST API** (`pulls.get`, release-please), so they **usually fail inside act** without a real `GITHUB_TOKEN`; that is expected and the script still exits **0** after the first two workflows pass.
33
+
That script lists and runs **validate-plugin** and **test-skills** with `act push` (these **must** succeed - the script exits non-zero if either fails). It then runs **semantic-pull-request** (`act pull_request` + [`.github/act/event-pull_request.json`](act/event-pull_request.json)) and **release-please** (`act push`) as **extra smoke tests**. Those two workflows call the **GitHub REST API** (`pulls.get`, release-please), so they **usually fail inside act** without a real `GITHUB_TOKEN`; that is expected and the script still exits **0** after the first two workflows pass.
|**`GITHUB_TOKEN`**| Injected automatically for each job as `secrets.GITHUB_TOKEN` (scoped to the repo, permissions from the workflow `permissions:` block). You do **not** add it under **Settings → Secrets**. |**Not** the same as GitHub’s token. act may set a placeholder or empty value; it does **not** mint a real token that can call `api.github.com` like the hosted runner. To exercise API-using actions locally you must pass a token yourself (e.g. `act … -s GITHUB_TOKEN=…` with a fine-scoped PAT)—optional and easy to get wrong, so we treat API workflows as **CI-only** for “full success.” |
88
+
|**`GITHUB_TOKEN`**| Injected automatically for each job as `secrets.GITHUB_TOKEN` (scoped to the repo, permissions from the workflow `permissions:` block). You do **not** add it under **Settings → Secrets**. |**Not** the same as GitHub’s token. act may set a placeholder or empty value; it does **not** mint a real token that can call `api.github.com` like the hosted runner. To exercise API-using actions locally you must pass a token yourself (e.g. `act … -s GITHUB_TOKEN=…` with a fine-scoped PAT)-optional and easy to get wrong, so we treat API workflows as **CI-only** for “full success.” |
89
89
|`import yaml` in Python | Works after we install **`python3-yaml`** via `apt` in the workflow | Same; that step exists so act matches GitHub |
90
90
|**release-please** / **semantic PR** actions | Full GitHub API + real `GITHUB_TOKEN`| May fail or partially run without a PAT; use for YAML/container smoke tests |
91
91
@@ -100,5 +100,5 @@ If you use [Task](https://taskfile.dev/), [`Taskfile.yaml`](../Taskfile.yaml) de
100
100
101
101
## See also
102
102
103
-
-[CONTRIBUTING.md — Development setup](../CONTRIBUTING.md#optional-run-ci-workflows-locally-with-act)
103
+
-[CONTRIBUTING.md - Development setup](../CONTRIBUTING.md#optional-run-ci-workflows-locally-with-act)
-`keeper-admin`— Keeper Commander (`keeper`): vault, enterprise admin, PAM, rotation, and related command references.
14
-
-`keeper-setup`— Installing and configuring the KSM and Commander CLIs, regions, and troubleshooting.
15
-
-**Distribution**— Claude Code plugin metadata (`.claude-plugin/`), marketplace listing, and install paths via [Vercel Skills CLI](https://github.com/vercel-labs/skills) (`npx skills add`) or manual copy into an agent’s skills directory.
16
-
-**Documentation**— README, CONTRIBUTING, SECURITY, `TEST_PROMPTS.md`, and links to official Keeper docs (Secrets Manager overview, Commander overview, Keeper notation).
17
-
-**CI**— GitHub Actions workflows to validate plugin JSON, marketplace JSON, SKILL frontmatter, reference files, and skill trigger/content checks; `python3-yaml` installed in workflows for reliable frontmatter parsing locally and on runners.
18
-
-**Developer tooling**—`Taskfile` tasks for Markdown (`task fmt`), dependencies (`task install`), and running CI locally with [act](https://github.com/nektos/act) (`task act`); [`.github/ACT.md`](.github/ACT.md) documents local workflow runs.
-`keeper-admin`- Keeper Commander (`keeper`): vault, enterprise admin, PAM, rotation, and related command references.
14
+
-`keeper-setup`- Installing and configuring the KSM and Commander CLIs, regions, and troubleshooting.
15
+
-**Distribution**- Claude Code plugin metadata (`.claude-plugin/`), marketplace listing, and install paths via [Vercel Skills CLI](https://github.com/vercel-labs/skills) (`npx skills add`) or manual copy into an agent’s skills directory.
16
+
-**Documentation**- README, CONTRIBUTING, SECURITY, `TEST_PROMPTS.md`, and links to official Keeper docs (Secrets Manager overview, Commander overview, Keeper notation).
17
+
-**CI**- GitHub Actions workflows to validate plugin JSON, marketplace JSON, SKILL frontmatter, reference files, and skill trigger/content checks; `python3-yaml` installed in workflows for reliable frontmatter parsing locally and on runners.
18
+
-**Developer tooling**-`Taskfile` tasks for Markdown (`task fmt`), dependencies (`task install`), and running CI locally with [act](https://github.com/nektos/act) (`task act`); [`.github/ACT.md`](.github/ACT.md) documents local workflow runs.
Copy file name to clipboardExpand all lines: CONTRIBUTING.md
+18-18Lines changed: 18 additions & 18 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -73,8 +73,8 @@ This repo is Markdown-only (no build step for the skills themselves). To run the
73
73
74
74
### Required: Task and Cargo
75
75
76
-
1.**[Task](https://taskfile.dev/installation/)**— install the `task` CLI so you can run tasks from [`Taskfile.yaml`](Taskfile.yaml) (`task fmt`, `task install`, etc.).
77
-
2.**[Rust and Cargo](https://doc.rust-lang.org/cargo/getting-started/installation.html)**— required because `task install` uses [cargo-binstall](https://github.com/cargo-bins/cargo-binstall) to pull prebuilt binaries (e.g. [rumdl](https://github.com/rvben/rumdl)).
76
+
1.**[Task](https://taskfile.dev/installation/)**- install the `task` CLI so you can run tasks from [`Taskfile.yaml`](Taskfile.yaml) (`task fmt`, `task install`, etc.).
77
+
2.**[Rust and Cargo](https://doc.rust-lang.org/cargo/getting-started/installation.html)**- required because `task install` uses [cargo-binstall](https://github.com/cargo-bins/cargo-binstall) to pull prebuilt binaries (e.g. [rumdl](https://github.com/rvben/rumdl)).
78
78
79
79
Then clone and install dev tools:
80
80
@@ -113,9 +113,9 @@ Pull requests are checked by **Semantic PR** (`.github/workflows/semantic-pull-r
113
113
114
114
#### `version.txt` (how the version is updated)
115
115
116
-
-**Role**— One line, semver only (e.g. `1.2.3`). With **`release-type: simple`** in `release-please-config.json`, this file is the **canonical project version** release-please reads and writes.
117
-
-**Normal workflow**—**Do not** edit `version.txt` by hand to ship a release. Land conventional commits on `main`, let release-please open its **release PR**, review it, and **merge that PR**. The PR updates `version.txt` together with `.release-please-manifest.json`, `CHANGELOG.md`, and the `version` fields in `.claude-plugin/plugin.json` and `marketplace.json` (see `extra-files` in `release-please-config.json`).
118
-
-**Avoid drift**— If you ever change a version **outside** that flow (unusual), update **every** file release-please keeps in sync so they all match; mismatches break automation and CI expectations.
116
+
-**Role**- One line, semver only (e.g. `1.2.3`). With **`release-type: simple`** in `release-please-config.json`, this file is the **canonical project version** release-please reads and writes.
117
+
-**Normal workflow**-**Do not** edit `version.txt` by hand to ship a release. Land conventional commits on `main`, let release-please open its **release PR**, review it, and **merge that PR**. The PR updates `version.txt` together with `.release-please-manifest.json`, `CHANGELOG.md`, and the `version` fields in `.claude-plugin/plugin.json` and `marketplace.json` (see `extra-files` in `release-please-config.json`).
118
+
-**Avoid drift**- If you ever change a version **outside** that flow (unusual), update **every** file release-please keeps in sync so they all match; mismatches break automation and CI expectations.
119
119
120
120
### Optional: run CI workflows locally with [act](https://github.com/nektos/act)
121
121
@@ -276,30 +276,30 @@ ksm secret list
276
276
277
277
Focus on:
278
278
279
-
-**When to use**— Clarify skill purpose and when agent should use it
280
-
-**Prerequisites**— What users need before using
281
-
-**Core concepts**— Key ideas explained simply
282
-
-**Common patterns**— Most used workflows
283
-
-**Guardrails**— Security and safety guidelines
279
+
-**When to use**- Clarify skill purpose and when agent should use it
280
+
-**Prerequisites**- What users need before using
281
+
-**Core concepts**- Key ideas explained simply
282
+
-**Common patterns**- Most used workflows
283
+
-**Guardrails**- Security and safety guidelines
284
284
285
285
### Reference Files
286
286
287
287
Focus on:
288
288
289
-
-**Complete reference**— All commands and options
290
-
-**Examples**— Real-world usage patterns
291
-
-**Troubleshooting**— Common issues and solutions
292
-
-**Best practices**— Recommended approaches
289
+
-**Complete reference**- All commands and options
290
+
-**Examples**- Real-world usage patterns
291
+
-**Troubleshooting**- Common issues and solutions
292
+
-**Best practices**- Recommended approaches
293
293
294
294
## Versioning
295
295
296
-
**Plugin / repo version**—[release-please](https://github.com/googleapis/release-please) manages **one** semver for the whole distribution: `version.txt`, `.release-please-manifest.json`, `CHANGELOG.md`, and the `version` fields in **`.claude-plugin/plugin.json`** and **`.claude-plugin/marketplace.json`** (see `release-please-config.json` → `extra-files`). It does **not** bump per-skill versions; skills under `skills/` ship as part of that plugin release.
296
+
**Plugin / repo version**-[release-please](https://github.com/googleapis/release-please) manages **one** semver for the whole distribution: `version.txt`, `.release-please-manifest.json`, `CHANGELOG.md`, and the `version` fields in **`.claude-plugin/plugin.json`** and **`.claude-plugin/marketplace.json`** (see `release-please-config.json` → `extra-files`). It does **not** bump per-skill versions; skills under `skills/` ship as part of that plugin release.
297
297
298
298
**Change significance** (for commit messages and changelog tone; not separate skill semver in this repo):
299
299
300
-
-**MAJOR**— Breaking changes to command syntax or CLI
0 commit comments