diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml index db9cf55..1c77082 100644 --- a/.github/workflows/build.yml +++ b/.github/workflows/build.yml @@ -34,6 +34,7 @@ jobs: uses: actions/checkout@v5 with: fetch-depth: 1 # shallow clone + persist-credentials: false - name: Install mise uses: jdx/mise-action@v3.6.2 with: diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index 28e26b1..a880894 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -25,6 +25,8 @@ jobs: steps: - name: Checkout repository uses: actions/checkout@v5 + with: + persist-credentials: false - name: Install, build, and upload site uses: withastro/action@v6 with: diff --git a/.github/zizmor.yml b/.github/zizmor.yml new file mode 100644 index 0000000..8257644 --- /dev/null +++ b/.github/zizmor.yml @@ -0,0 +1,11 @@ +# zizmor: https://docs.zizmor.sh/configuration/ +rules: + # Default since v1.20 is hash-pin for all actions; we require tag/branch/SHA pins. + unpinned-uses: + config: + policies: + "*": ref-pin + # Minimal pull_request_target job (PR title only); trigger is intentional for forks. + dangerous-triggers: + ignore: + - pull-request-lint.yml diff --git a/AGENTS.md b/AGENTS.md index f4e950e..a466d6c 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -104,8 +104,9 @@ Run `mise tasks --all` (with `MISE_EXPERIMENTAL=1`) for the full list. Common co - **`mise run security:secrets`** — Gitleaks at repo root. - **`mise run security:sast`** — Semgrep on the repo (root; includes **`agent/`** Python among paths). - **`mise run security:deps`** — OSV Scanner on **`yarn.lock`** (all JS workspaces) and **`agent/uv.lock`**. -- **`mise run security`** — Runs **`security:secrets`** then **`security:sast`**. +- **`mise run security`** — Runs **`security:secrets`**, **`security:deps`**, **`security:sast`**, **`security:grype`**, **`security:retire`**, **`security:gh-actions`**, and **`//agent:security`**. - **`mise run security:retire`** — Retire.js on CDK, CLI, and docs packages. +- **`mise run security:gh-actions`** — Static analysis of GitHub Actions under **`.github/`** ([zizmor](https://github.com/zizmorcore/zizmor)). - **`mise run hooks:install`** — Re-install **[prek](https://github.com/j178/prek)** git hooks (also run automatically at the end of **`mise run install`** inside a Git checkout). See [CONTRIBUTING.md](./CONTRIBUTING.md) if `core.hooksPath` blocks install. - **`mise run hooks:run`** — Run the same **pre-commit** and **pre-push** hook stages on all files (local verification). diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 5c5edd1..f5343db 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -42,7 +42,7 @@ When planning edits, use **[AGENTS.md](./AGENTS.md)** at the repo root for **whe This repository uses [mise](https://mise.jdx.dev/) for tool versions and tasks. The root **`mise.toml`** enables [monorepo tasks](https://mise.jdx.dev/tasks/monorepo.html) with **`[monorepo].config_roots`** for **`cdk`**, **`agent`**, **`cli`**, and **`docs`**. -- After cloning, run **`mise trust`** in the repository root (and in **`agent/`** if you use tasks there in isolation) so mise will load **`mise.toml`** files. See [mise trust](https://mise.jdx.dev/cli/trust.html). +- After cloning, run **`mise trust`** in the repository root (and in **`agent/`** if you use tasks there in isolation) so mise will load **`mise.toml`** files. See [mise trust](https://mise.jdx.dev/cli/trust.html). **New to mise?** Activate it in your shell first ([`eval "$(mise activate zsh)"`](https://mise.jdx.dev/getting-started.html) or the bash equivalent in `~/.zshrc` / `~/.bashrc`), run **`mise install`**, then enable **Yarn** with **`corepack enable`** and **`corepack prepare yarn@1.22.22 --activate`** before **`mise run install`** (otherwise **`yarn: command not found`** is common). Full sequence and troubleshooting: [Developer guide — Installation](./docs/guides/DEVELOPER_GUIDE.md#installation). - Set **`export MISE_EXPERIMENTAL=1`** in your shell (or add it to your environment) when using **namespaced tasks** such as **`mise //cdk:build`** or **`mise run //agent:install`**. Root tasks like **`mise run install`** and **`mise run build`** work without cross-package references and are enough for most workflows. - From the repo root: **`mise run install`** runs **`yarn install`** and **`mise run install`** in **`agent/`**. **`mise run build`** runs **`//agent:quality`** first (the CDK stack bundles the agent image), then **`//cdk:build`**, **`//cli:build`**, and **`//docs:build`** in order. diff --git a/docs/guides/DEVELOPER_GUIDE.md b/docs/guides/DEVELOPER_GUIDE.md index 79364a4..38707c7 100644 --- a/docs/guides/DEVELOPER_GUIDE.md +++ b/docs/guides/DEVELOPER_GUIDE.md @@ -67,17 +67,14 @@ Keep each repo you onboard **clear and automatable**: documented build/test comm ## Installation -Clone the repository and open the project root (commands below assume your shell is at the repo root). - -```bash -git clone https://github.com/aws-samples/sample-autonomous-cloud-coding-agents.git -cd sample-autonomous-cloud-coding-agents -``` +Commands below assume your shell is at the repo root after you clone. ### Pre-requisites -- An AWS account. We recommend you deploy this solution in a new account -- [AWS CLI](https://aws.amazon.com/cli/): configure your credentials +**Install and configure yourself (not provided by this repository’s mise files):** + +- An AWS account (we recommend a dedicated account for this solution). +- [AWS CLI](https://aws.amazon.com/cli/) with credentials configured, for example: ``` aws configure --profile [your-profile] @@ -87,13 +84,21 @@ Default region name [None]: us-east-1 Default output format [None]: json ``` -- [Node](https://nodejs.org/en) >= v22.0.0 -- [AWS CDK](https://github.com/aws/aws-cdk/releases/tag/v2.233.0) >= 2.233.0 -- [Python](https://www.python.org/downloads/) >=3.9 -- [Yarn](https://classic.yarnpkg.com/lang/en/docs/cli/install/) >= 1.22.19 -- [mise](https://mise.jdx.dev/getting-started.html) (required for local agent Python tasks and checks) -- [Docker](https://docs.docker.com/engine/install/) -- A **GitHub personal access token** (PAT) with permission to access every repository you onboard (clone, push to branches, create and update pull requests)—often a fine-grained token scoped to **your fork** of `awslabs/agent-plugins` if you follow the fork workflow under **Repository preparation** at the start of this guide. After deployment, store it in the Secrets Manager secret the stack creates ([Post-deployment setup](#post-deployment-setup)); for local agent runs, export `GITHUB_TOKEN` (see **Local testing** below). Required scopes are documented in `agent/README.md`. +- [Docker](https://docs.docker.com/engine/install/) — for local agent runs and CDK asset builds. +- [mise](https://mise.jdx.dev/getting-started.html) — task runner and version manager for Node, security tools, and (under `agent/`) Python. Install from the official guide; it is **not** installed via npm. +- **AWS CDK CLI** ≥ 2.233.0 — install globally with npm **after** mise is active so it uses the same Node as this repo (see [Set up your toolchain](#set-up-your-toolchain)): `npm install -g aws-cdk`. +- A **GitHub personal access token** (PAT) with permission to access every repository you onboard (clone, push to branches, create and update pull requests)—often a fine-grained token scoped to **your fork** of `awslabs/agent-plugins` if you follow the fork workflow under **Repository preparation**. After deployment, store it in the Secrets Manager secret the stack creates ([Post-deployment setup](#post-deployment-setup)); for local agent runs, export `GITHUB_TOKEN` (see **Local testing**). Required scopes are documented in `agent/README.md`. + +**Versions this repo pins via mise (no separate Node/Yarn/Python install needed for the standard path):** + +| Tool | Where it is defined | When it is installed | +|------|---------------------|----------------------| +| **Node.js** 22.x | Root `mise.toml` | `mise install` from the repo root | +| **Yarn Classic** (1.22.x) | Not in mise — use Corepack with Node (see below) | After `corepack enable` and `corepack prepare yarn@…` | +| **Python** + **uv** | `agent/mise.toml` | `mise run install` (runs `mise run install` inside `agent/`) | +| gitleaks, semgrep, osv-scanner, grype, zizmor, prek, … | Root `mise.toml` | `mise install` from the repo root | + +You do **not** need standalone installs of Node or Yarn from nodejs.org or the Yarn website if you follow [Set up your toolchain](#set-up-your-toolchain). #### One-time AWS account setup @@ -105,21 +110,93 @@ aws xray update-trace-segment-destination --destination CloudWatchLogs Without this, `cdk deploy` will fail with: *"X-Ray Delivery Destination is supported with CloudWatch Logs as a Trace Segment Destination."* -Install [mise](https://mise.jdx.dev/getting-started.html) using the official guide; it is not installed via npm. For the Node-based CLIs, run: +### Set up your toolchain -```bash -npm install -g npm aws-cdk -``` +1. **Install mise** — follow [Getting started](https://mise.jdx.dev/getting-started.html). + +2. **Activate mise in your shell** so `node`, task tools, and project tasks resolve correctly. Add one line to `~/.zshrc` or `~/.bashrc`: + + ```bash + eval "$(mise activate zsh)" # or: eval "$(mise activate bash)" + ``` + + Reload the file (`source ~/.zshrc`) or open a new terminal. Without this step, your shell may keep using a system Node (or no `yarn`), and `mise run install` can fail with **`yarn: command not found`**. + +3. **Clone the repository** and change into it: + + ```bash + git clone https://github.com/aws-samples/sample-autonomous-cloud-coding-agents.git + cd sample-autonomous-cloud-coding-agents + ``` + +4. **Trust this repository’s mise config.** Mise refuses to apply project-local settings until you trust them (security feature): + + ```bash + mise trust + ``` + +5. **Install tools from the root `mise.toml`** (Node 22, security scanners, prek, etc.): -Install repository dependencies and run an initial build before making changes: + ```bash + mise install + ``` + +6. **Enable Yarn via Corepack.** Node ships with Corepack, but Yarn is not on your PATH until Corepack is enabled. This monorepo uses **Yarn Classic** (1.x) workspaces: + + ```bash + corepack enable + corepack prepare yarn@1.22.22 --activate + ``` + + The `prepare` line installs a 1.22.x release compatible with the workspace (`yarn.lock` / engines expectations). If `yarn` is still missing, confirm step 2 (shell activation) and that `which node` points into your mise shims. + +7. **Sanity check** (optional): + + ```bash + node --version # expect v22.x + yarn --version # expect 1.22.x + ``` + +8. **Install the AWS CDK CLI** using the same Node as mise: + + ```bash + npm install -g aws-cdk + ``` + +9. **Install workspace dependencies and build.** Namespaced mise tasks require experimental mode: + + ```bash + export MISE_EXPERIMENTAL=1 + mise run install + mise run build + ``` + +`mise run install` runs `yarn install` for the Yarn workspaces (`cdk`, `cli`, `docs`), then `mise run install` in `agent/` for Python dependencies, and installs [prek](https://github.com/j178/prek) git hooks when you are inside a Git checkout. + +### First time with mise? Troubleshooting + +Use this section if **`mise run install`** fails or versions look wrong. + +| Symptom | What to check | +|---------|----------------| +| **`yarn: command not found`** | Mise shell activation (step 2), then `corepack enable` and `corepack prepare yarn@1.22.22 --activate` (step 6). | +| **`node` is not v22** | Shell activation (step 2); run `mise install` in the repo root (step 5). | +| Mise errors about **untrusted** config | From the repo root: `mise trust`, then `mise install` again. | +| **`MISE_EXPERIMENTAL` required** | Export `MISE_EXPERIMENTAL=1` for tasks like `mise //cdk:build` (see [CONTRIBUTING.md](../../CONTRIBUTING.md)). | + +Minimal recovery sequence: ```bash +eval "$(mise activate zsh)" # or bash; add permanently to your shell rc file +cd /path/to/sample-autonomous-cloud-coding-agents +mise trust +mise install +corepack enable +corepack prepare yarn@1.22.22 --activate +export MISE_EXPERIMENTAL=1 mise run install -mise run build ``` -`mise run install` runs `yarn install` for the workspaces and `mise run install` in `agent/` for Python dependencies. - ### Suggested development flow Use this order to iterate quickly and catch issues early: diff --git a/docs/src/content/docs/developer-guide/Contributing.md b/docs/src/content/docs/developer-guide/Contributing.md index 3a2323d..75f8267 100644 --- a/docs/src/content/docs/developer-guide/Contributing.md +++ b/docs/src/content/docs/developer-guide/Contributing.md @@ -46,7 +46,7 @@ When planning edits, use **[AGENTS.md](/design/agents)** at the repo root for ** This repository uses [mise](https://mise.jdx.dev/) for tool versions and tasks. The root **`mise.toml`** enables [monorepo tasks](https://mise.jdx.dev/tasks/monorepo.html) with **`[monorepo].config_roots`** for **`cdk`**, **`agent`**, **`cli`**, and **`docs`**. -- After cloning, run **`mise trust`** in the repository root (and in **`agent/`** if you use tasks there in isolation) so mise will load **`mise.toml`** files. See [mise trust](https://mise.jdx.dev/cli/trust.html). +- After cloning, run **`mise trust`** in the repository root (and in **`agent/`** if you use tasks there in isolation) so mise will load **`mise.toml`** files. See [mise trust](https://mise.jdx.dev/cli/trust.html). **New to mise?** Activate it in your shell first ([`eval "$(mise activate zsh)"`](https://mise.jdx.dev/getting-started.html) or the bash equivalent in `~/.zshrc` / `~/.bashrc`), run **`mise install`**, then enable **Yarn** with **`corepack enable`** and **`corepack prepare yarn@1.22.22 --activate`** before **`mise run install`** (otherwise **`yarn: command not found`** is common). Full sequence and troubleshooting: [Developer guide — Installation](/developer-guide/introduction#installation). - Set **`export MISE_EXPERIMENTAL=1`** in your shell (or add it to your environment) when using **namespaced tasks** such as **`mise //cdk:build`** or **`mise run //agent:install`**. Root tasks like **`mise run install`** and **`mise run build`** work without cross-package references and are enough for most workflows. - From the repo root: **`mise run install`** runs **`yarn install`** and **`mise run install`** in **`agent/`**. **`mise run build`** runs **`//agent:quality`** first (the CDK stack bundles the agent image), then **`//cdk:build`**, **`//cli:build`**, and **`//docs:build`** in order. diff --git a/docs/src/content/docs/developer-guide/Installation.md b/docs/src/content/docs/developer-guide/Installation.md index 3ee8646..1e3a486 100644 --- a/docs/src/content/docs/developer-guide/Installation.md +++ b/docs/src/content/docs/developer-guide/Installation.md @@ -2,17 +2,14 @@ title: Installation --- -Clone the repository and open the project root (commands below assume your shell is at the repo root). - -```bash -git clone https://github.com/aws-samples/sample-autonomous-cloud-coding-agents.git -cd sample-autonomous-cloud-coding-agents -``` +Commands below assume your shell is at the repo root after you clone. ### Pre-requisites -- An AWS account. We recommend you deploy this solution in a new account -- [AWS CLI](https://aws.amazon.com/cli/): configure your credentials +**Install and configure yourself (not provided by this repository’s mise files):** + +- An AWS account (we recommend a dedicated account for this solution). +- [AWS CLI](https://aws.amazon.com/cli/) with credentials configured, for example: ``` aws configure --profile [your-profile] @@ -22,13 +19,21 @@ Default region name [None]: us-east-1 Default output format [None]: json ``` -- [Node](https://nodejs.org/en) >= v22.0.0 -- [AWS CDK](https://github.com/aws/aws-cdk/releases/tag/v2.233.0) >= 2.233.0 -- [Python](https://www.python.org/downloads/) >=3.9 -- [Yarn](https://classic.yarnpkg.com/lang/en/docs/cli/install/) >= 1.22.19 -- [mise](https://mise.jdx.dev/getting-started.html) (required for local agent Python tasks and checks) -- [Docker](https://docs.docker.com/engine/install/) -- A **GitHub personal access token** (PAT) with permission to access every repository you onboard (clone, push to branches, create and update pull requests)—often a fine-grained token scoped to **your fork** of `awslabs/agent-plugins` if you follow the fork workflow under **Repository preparation** at the start of this guide. After deployment, store it in the Secrets Manager secret the stack creates ([Post-deployment setup](#post-deployment-setup)); for local agent runs, export `GITHUB_TOKEN` (see **Local testing** below). Required scopes are documented in `agent/README.md`. +- [Docker](https://docs.docker.com/engine/install/) — for local agent runs and CDK asset builds. +- [mise](https://mise.jdx.dev/getting-started.html) — task runner and version manager for Node, security tools, and (under `agent/`) Python. Install from the official guide; it is **not** installed via npm. +- **AWS CDK CLI** ≥ 2.233.0 — install globally with npm **after** mise is active so it uses the same Node as this repo (see [Set up your toolchain](#set-up-your-toolchain)): `npm install -g aws-cdk`. +- A **GitHub personal access token** (PAT) with permission to access every repository you onboard (clone, push to branches, create and update pull requests)—often a fine-grained token scoped to **your fork** of `awslabs/agent-plugins` if you follow the fork workflow under **Repository preparation**. After deployment, store it in the Secrets Manager secret the stack creates ([Post-deployment setup](#post-deployment-setup)); for local agent runs, export `GITHUB_TOKEN` (see **Local testing**). Required scopes are documented in `agent/README.md`. + +**Versions this repo pins via mise (no separate Node/Yarn/Python install needed for the standard path):** + +| Tool | Where it is defined | When it is installed | +|------|---------------------|----------------------| +| **Node.js** 22.x | Root `mise.toml` | `mise install` from the repo root | +| **Yarn Classic** (1.22.x) | Not in mise — use Corepack with Node (see below) | After `corepack enable` and `corepack prepare yarn@…` | +| **Python** + **uv** | `agent/mise.toml` | `mise run install` (runs `mise run install` inside `agent/`) | +| gitleaks, semgrep, osv-scanner, grype, zizmor, prek, … | Root `mise.toml` | `mise install` from the repo root | + +You do **not** need standalone installs of Node or Yarn from nodejs.org or the Yarn website if you follow [Set up your toolchain](#set-up-your-toolchain). #### One-time AWS account setup @@ -40,21 +45,93 @@ aws xray update-trace-segment-destination --destination CloudWatchLogs Without this, `cdk deploy` will fail with: *"X-Ray Delivery Destination is supported with CloudWatch Logs as a Trace Segment Destination."* -Install [mise](https://mise.jdx.dev/getting-started.html) using the official guide; it is not installed via npm. For the Node-based CLIs, run: +### Set up your toolchain -```bash -npm install -g npm aws-cdk -``` +1. **Install mise** — follow [Getting started](https://mise.jdx.dev/getting-started.html). + +2. **Activate mise in your shell** so `node`, task tools, and project tasks resolve correctly. Add one line to `~/.zshrc` or `~/.bashrc`: + + ```bash + eval "$(mise activate zsh)" # or: eval "$(mise activate bash)" + ``` + + Reload the file (`source ~/.zshrc`) or open a new terminal. Without this step, your shell may keep using a system Node (or no `yarn`), and `mise run install` can fail with **`yarn: command not found`**. + +3. **Clone the repository** and change into it: + + ```bash + git clone https://github.com/aws-samples/sample-autonomous-cloud-coding-agents.git + cd sample-autonomous-cloud-coding-agents + ``` + +4. **Trust this repository’s mise config.** Mise refuses to apply project-local settings until you trust them (security feature): + + ```bash + mise trust + ``` + +5. **Install tools from the root `mise.toml`** (Node 22, security scanners, prek, etc.): -Install repository dependencies and run an initial build before making changes: + ```bash + mise install + ``` + +6. **Enable Yarn via Corepack.** Node ships with Corepack, but Yarn is not on your PATH until Corepack is enabled. This monorepo uses **Yarn Classic** (1.x) workspaces: + + ```bash + corepack enable + corepack prepare yarn@1.22.22 --activate + ``` + + The `prepare` line installs a 1.22.x release compatible with the workspace (`yarn.lock` / engines expectations). If `yarn` is still missing, confirm step 2 (shell activation) and that `which node` points into your mise shims. + +7. **Sanity check** (optional): + + ```bash + node --version # expect v22.x + yarn --version # expect 1.22.x + ``` + +8. **Install the AWS CDK CLI** using the same Node as mise: + + ```bash + npm install -g aws-cdk + ``` + +9. **Install workspace dependencies and build.** Namespaced mise tasks require experimental mode: + + ```bash + export MISE_EXPERIMENTAL=1 + mise run install + mise run build + ``` + +`mise run install` runs `yarn install` for the Yarn workspaces (`cdk`, `cli`, `docs`), then `mise run install` in `agent/` for Python dependencies, and installs [prek](https://github.com/j178/prek) git hooks when you are inside a Git checkout. + +### First time with mise? Troubleshooting + +Use this section if **`mise run install`** fails or versions look wrong. + +| Symptom | What to check | +|---------|----------------| +| **`yarn: command not found`** | Mise shell activation (step 2), then `corepack enable` and `corepack prepare yarn@1.22.22 --activate` (step 6). | +| **`node` is not v22** | Shell activation (step 2); run `mise install` in the repo root (step 5). | +| Mise errors about **untrusted** config | From the repo root: `mise trust`, then `mise install` again. | +| **`MISE_EXPERIMENTAL` required** | Export `MISE_EXPERIMENTAL=1` for tasks like `mise //cdk:build` (see [CONTRIBUTING.md](/developer-guide/contributing)). | + +Minimal recovery sequence: ```bash +eval "$(mise activate zsh)" # or bash; add permanently to your shell rc file +cd /path/to/sample-autonomous-cloud-coding-agents +mise trust +mise install +corepack enable +corepack prepare yarn@1.22.22 --activate +export MISE_EXPERIMENTAL=1 mise run install -mise run build ``` -`mise run install` runs `yarn install` for the workspaces and `mise run install` in `agent/` for Python dependencies. - ### Suggested development flow Use this order to iterate quickly and catch issues early: diff --git a/mise.toml b/mise.toml index 088c750..93c6198 100644 --- a/mise.toml +++ b/mise.toml @@ -14,6 +14,7 @@ gitleaks = "latest" semgrep = "latest" osv-scanner = "latest" "grype" = "0.110.0" +"aqua:zizmorcore/zizmor" = "1.23.1" [monorepo] config_roots = ["cdk", "agent", "cli", "docs"] @@ -77,6 +78,11 @@ run = [ description = "Retire.js (CDK, CLI, docs)" run = "npx retire --path cdk --severity high --ignore \"node_modules/**,cdk.out/**,cdk/cdk.out/**\" && cd cli && npm run security:retire && cd ../docs && npm run security:retire" +[tasks."security:gh-actions"] +description = "Static analysis of GitHub Actions workflows (zizmor)" +# Offline: no GitHub API for online-only rules; config in .github/zizmor.yml +run = "zizmor --offline .github" + [tasks.security] description = "Run security scans" run = [ @@ -85,6 +91,7 @@ run = [ { task = "security:sast" }, { task = "security:grype" }, { task = "security:retire" }, + { task = "security:gh-actions" }, "MISE_EXPERIMENTAL=1 mise //agent:security", ]