# zizmorcore/zizmor-action architecture

> Architecture diagram of the GitHub repository zizmorcore/zizmor-action, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-14). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/zizmorcore/zizmor-action
- Repository: https://github.com/zizmorcore/zizmor-action

## Overview

#### Purpose and Entry Point
`zizmor-action` is a container-based GitHub Action that runs the external `zizmor` security auditor against workflow/action inputs. The action contract and runtime launcher are defined by `action.yml` and `action.sh`; consumers invoke it through `uses:` in a GitHub Actions job.

#### Action Contract
`action.yml` exposes user-facing inputs for target collection, auditing behavior, filtering, version selection, GitHub token access, output mode, configuration, and no-input handling. Its principal output is `output-file`, a SARIF path when Advanced Security mode is enabled. Runtime behavior is implemented by `action.sh`.

Paths: `action.yml`, `action.sh`

#### Execution and Analysis Pipeline
The shell entrypoint reads Action inputs, obtains/runs the selected `zizmor` version in a container runtime, and forwards collection/audit options such as inputs, persona, online audits, severity/confidence filters, and config path. `zizmor` is the analysis engine and may inspect local checkout content, remote repositories, and GitHub metadata depending on inputs and enabled audits.

Paths: `action.sh`, `action.yml`

#### Result Delivery Modes
Advanced Security is the default boundary: analysis emits SARIF, exposes its path through `output-file`, and relies on GitHub code-scanning ingestion. In non-Advanced-Security mode, findings are written to logs; optional GitHub workflow annotations are supported but mutually exclusive with SARIF/Advanced Security. Advanced Security findings do not fail the workflow merely because findings exist; tool/runtime failures remain meaningful failures.

Paths: `action.yml`, `action.sh`

#### External Services, Permissions, and Runtime
Execution requires Docker or a compatible container runtime, making Linux GitHub-hosted runners the intended environment. Online audits use the GitHub REST API through the supplied/default `github.token`. SARIF integration requires `security-events: write`; private-repository Advanced Security analysis can additionally require `contents: read` and `actions: read`.

Paths: `action.yml`, `README.md`

#### Version Supply and Maintenance
The action supports an exact `zizmor` version or `latest`. Version metadata is maintained under `support/versions`, with a synchronization script that is likely invoked by repository automation. This separates the user-selected tool version from the action’s own implementation.

Paths: `support/versions`, `support/sync-zizmor-versions.sh`, `.github/workflows/sync-zizmor-versions.yml`

#### Repository Automation Boundary
GitHub workflows validate the action itself and run security scanning/maintenance automation. These workflows are repository-internal consumers rather than the product runtime; the shipped product surface remains the action metadata plus shell launcher.

Paths: `.github/workflows/selftest.yml`, `.github/workflows/zizmor.yml`, `action.yml`

Main entry points: [`action.yml`](https://github.com/zizmorcore/zizmor-action/blob/main/action.yml) (Action contract), [`action.sh`](https://github.com/zizmorcore/zizmor-action/blob/main/action.sh) (Runtime launcher), [`support/versions`](https://github.com/zizmorcore/zizmor-action/blob/main/support/versions) (Version catalog), [`support/sync-zizmor-versions.sh`](https://github.com/zizmorcore/zizmor-action/blob/main/support/sync-zizmor-versions.sh) (Version sync script)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_consumer["GitHub Action consumer"]
  node_job["Consumer workflow job<br/>GitHub Actions job"]
  node_github_token{{"GitHub token<br/>credential"}}
end

subgraph group_product["Shipped action"]
  node_action_metadata["Action contract<br/>Action metadata<br/>[action.yml]"]
  node_launcher["Runtime launcher<br/>shell entrypoint<br/>[action.sh]"]
end

subgraph group_runtime["Analysis runtime"]
  node_checkout["Local checkout<br/>workflow content"]
  node_container_runtime{{"Container runtime<br/>Docker-compatible runtime"}}
  node_zizmor["zizmor auditor<br/>containerized analyzer"]
  node_github_api{{"GitHub REST API<br/>external API"}}
  node_sarif["SARIF result<br/>analysis artifact"]
  node_code_scanning["Code scanning<br/>GitHub ingestion"]
  node_logs_annotations["Logs or annotations<br/>result delivery"]
end

subgraph group_maintenance["Repository automation"]
  node_version_catalog["Version catalog<br/>version metadata"]
  node_version_sync["Version sync script<br/>maintenance script"]
  node_sync_workflow["Version sync workflow<br/>GitHub workflow"]
  node_selftest["Action self-test<br/>GitHub workflow<br/>[selftest.yml]"]
  node_repo_scan["Repository scan<br/>GitHub workflow<br/>[zizmor.yml]"]
end

node_job -->|"uses"| node_action_metadata
node_action_metadata -->|"declares entrypoint"| node_launcher
node_action_metadata -.->|"accepts token input"| node_github_token
node_launcher -->|"runs through"| node_container_runtime
node_container_runtime -->|"executes"| node_zizmor
node_launcher -->|"forwards audit options"| node_zizmor
node_zizmor -->|"inspects"| node_checkout
node_github_token -->|"authenticates"| node_github_api
node_zizmor -.->|"online audits"| node_github_api
node_zizmor -->|"Advanced Security mode"| node_sarif
node_sarif -->|"ingested by GitHub"| node_code_scanning
node_action_metadata -.->|"exposes output-file path"| node_sarif
node_zizmor -->|"non-Advanced-Security mode"| node_logs_annotations
node_sync_workflow -->|"runs"| node_version_sync
node_version_sync -->|"updates"| node_version_catalog
node_version_catalog -.->|"selects tool version"| node_launcher
node_selftest -->|"validates"| node_action_metadata
node_repo_scan -->|"scans"| node_action_metadata

click node_action_metadata "https://github.com/zizmorcore/zizmor-action/blob/main/action.yml"
click node_launcher "https://github.com/zizmorcore/zizmor-action/blob/main/action.sh"
click node_version_catalog "https://github.com/zizmorcore/zizmor-action/blob/main/support/versions"
click node_version_sync "https://github.com/zizmorcore/zizmor-action/blob/main/support/sync-zizmor-versions.sh"
click node_sync_workflow "https://github.com/zizmorcore/zizmor-action/blob/main/.github/workflows/sync-zizmor-versions.yml"
click node_selftest "https://github.com/zizmorcore/zizmor-action/blob/main/.github/workflows/selftest.yml"
click node_repo_scan "https://github.com/zizmorcore/zizmor-action/blob/main/.github/workflows/zizmor.yml"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_job,node_github_token toneBlue
class node_action_metadata,node_launcher toneAmber
class node_checkout,node_container_runtime,node_zizmor,node_github_api,node_sarif,node_code_scanning,node_logs_annotations toneMint
class node_version_catalog,node_version_sync,node_sync_workflow,node_selftest,node_repo_scan toneRose
```

## Components

### GitHub Action consumer

- **Consumer workflow job**: GitHub Actions job · Invokes the action with uses:.
- **GitHub token**: credential · Enables online audits and GitHub integration.

### Shipped action

- [Action contract](https://github.com/zizmorcore/zizmor-action/blob/main/action.yml): Action metadata · Defines inputs and the output-file output. · `action.yml`
- [Runtime launcher](https://github.com/zizmorcore/zizmor-action/blob/main/action.sh): shell entrypoint · Reads inputs and orchestrates the tool container. · `action.sh`

### Analysis runtime

- **Local checkout**: workflow content
- **Container runtime**: Docker-compatible runtime · Required on the Linux runner.
- **zizmor auditor**: containerized analyzer · Audits workflow and action inputs.
- **GitHub REST API**: external API · Used by enabled online audits.
- **SARIF result**: analysis artifact · Produced in Advanced Security mode.
- **Code scanning**: GitHub ingestion · Requires security-events: write.
- **Logs or annotations**: result delivery · Non-SARIF finding output; annotations are optional.

### Repository automation

- [Version catalog](https://github.com/zizmorcore/zizmor-action/blob/main/support/versions): version metadata · Supplies supported exact versions and latest. · `support/versions`
- [Version sync script](https://github.com/zizmorcore/zizmor-action/blob/main/support/sync-zizmor-versions.sh): maintenance script · `support/sync-zizmor-versions.sh`
- [Version sync workflow](https://github.com/zizmorcore/zizmor-action/blob/main/.github/workflows/sync-zizmor-versions.yml): GitHub workflow · `.github/workflows/sync-zizmor-versions.yml`
- [Action self-test](https://github.com/zizmorcore/zizmor-action/blob/main/.github/workflows/selftest.yml): GitHub workflow · Repository-internal consumer validating the action. · `.github/workflows/selftest.yml`
- [Repository scan](https://github.com/zizmorcore/zizmor-action/blob/main/.github/workflows/zizmor.yml): GitHub workflow · Repository-internal security automation. · `.github/workflows/zizmor.yml`

## Connections

- Consumer workflow job → Action contract: uses
- Action contract → Runtime launcher: declares entrypoint
- Action contract → GitHub token: accepts token input
- Runtime launcher → Container runtime: runs through
- Container runtime → zizmor auditor: executes
- Runtime launcher → zizmor auditor: forwards audit options
- zizmor auditor → Local checkout: inspects
- GitHub token → GitHub REST API: authenticates
- zizmor auditor → GitHub REST API: online audits
- zizmor auditor → SARIF result: Advanced Security mode
- SARIF result → Code scanning: ingested by GitHub
- Action contract → SARIF result: exposes output-file path
- zizmor auditor → Logs or annotations: non-Advanced-Security mode
- Version sync workflow → Version sync script: runs
- Version sync script → Version catalog: updates
- Version catalog → Runtime launcher: selects tool version
- Action self-test → Action contract: validates
- Repository scan → Action contract: scans