Add GitHub Actions annotations output

Author: itscloud0

CHANGELOG.md

@@ -1,5 +1,10 @@
 # Changelog
 
+## v0.2.0 - 2026-07-10
+
+- Added `--format github-annotations` for inline GitHub Actions workflow commands.
+- Documented annotation output for CI users.
+
 ## v0.1.0 - 2026-06-16
 
 - Initial release of `action-pin-check`.

README.md

@@ -78,6 +78,12 @@ Return JSON for automation:
 action-pin-check --format json --fail-on never
 ```
 
+Emit GitHub Actions workflow annotations for inline CI findings:
+
+```bash
+action-pin-check --format github-annotations --fail-on error
+```
+
 Fail CI only on hard errors, not version-tag warnings:
 
 ```bash
@@ -118,7 +124,6 @@ Local actions like `./local-action` and Docker actions like `docker://...` are i
 
 - Optional SARIF output for GitHub code scanning.
 - Config file for allowed tag refs.
-- Inline GitHub Actions annotations.
 - Safer fix suggestions that include action repository links.
 - Reusable workflow coverage.
 

RELEASE_NOTES.md

@@ -1,14 +1,12 @@
-# action-pin-check v0.1.0
+# action-pin-check v0.2.0
 
-Initial release.
+Feature release.
 
-`action-pin-check` audits GitHub Actions workflows for external action refs that are missing, branch-based, tag-based, or short SHA pins. It is local-first, dependency-free at runtime, and supports both text and JSON output.
+`action-pin-check` audits GitHub Actions workflows for external action refs that are missing, branch-based, tag-based, or short SHA pins. It is local-first, dependency-free at runtime, and now supports text, JSON, and GitHub Actions annotation output.
 
 Included:
 
-- CLI scanner for repository roots, workflow directories, or workflow files.
-- Text output for humans.
-- JSON output for automation.
-- `--fail-on` policy for CI gates.
-- Example unsafe workflow fixture.
-- Unit tests and GitHub Actions CI.
+- `--format github-annotations` for inline CI findings on exact workflow lines.
+- Existing text output for humans.
+- Existing JSON output for automation.
+- Existing `--fail-on` policy for CI gates.

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "action-pin-check"
-version = "0.1.0"
+version = "0.2.0"
 description = "Audit GitHub Actions workflows for mutable or missing action pins."
 readme = "README.md"
 requires-python = ">=3.9"

src/action_pin_check/__init__.py

@@ -1,3 +1,3 @@
 """Audit GitHub Actions workflows for mutable or missing action pins."""
 
-__version__ = "0.1.0"
+__version__ = "0.2.0"

src/action_pin_check/cli.py

@@ -22,7 +22,7 @@ def main(argv: Sequence[str] | None = None) -> int:
     )
     parser.add_argument(
         "--format",
-        choices=("text", "json"),
+        choices=("text", "json", "github-annotations"),
         default="text",
         help="Output format.",
     )
@@ -38,6 +38,10 @@ def main(argv: Sequence[str] | None = None) -> int:
     result = scan_path(args.path)
     if args.format == "json":
         print(json.dumps(result.to_dict(), indent=2, sort_keys=True))
+    elif args.format == "github-annotations":
+        annotations = _format_github_annotations(result)
+        if annotations:
+            print(annotations)
     else:
         print(_format_text(result))
 
@@ -78,5 +82,38 @@ def _format_text(result: ScanResult) -> str:
     return "\n".join(lines).rstrip()
 
 
+def _format_github_annotations(result: ScanResult) -> str:
+    lines = []
+    for finding in result.findings:
+        command = "error" if finding.severity == "error" else "warning"
+        props = [
+            f"file={_escape_annotation_property(finding.file)}",
+            f"title={_escape_annotation_property(finding.code)}",
+        ]
+        if finding.line > 0:
+            props.insert(1, f"line={finding.line}")
+        ref = f"@{finding.ref}" if finding.ref else ""
+        message = (
+            f"{finding.message} Fix: {finding.suggestion} "
+            f"uses: {finding.action}{ref}".rstrip()
+        )
+        lines.append(
+            f"::{command} {','.join(props)}::{_escape_annotation_data(message)}"
+        )
+    return "\n".join(lines)
+
+
+def _escape_annotation_data(value: str) -> str:
+    return value.replace("%", "%25").replace("\r", "%0D").replace("\n", "%0A")
+
+
+def _escape_annotation_property(value: str) -> str:
+    return (
+        _escape_annotation_data(value)
+        .replace(":", "%3A")
+        .replace(",", "%2C")
+    )
+
+
 if __name__ == "__main__":
     raise SystemExit(main(sys.argv[1:]))

tests/test_cli.py

@@ -40,6 +40,48 @@ def test_text_output_for_clean_workflow(self):
         self.assertEqual(code, 0)
         self.assertIn("OK:", stdout.getvalue())
 
+    def test_github_annotations_output_points_to_workflow_line(self):
+        with tempfile.TemporaryDirectory() as tmp:
+            workflow = Path(tmp) / "ci.yml"
+            workflow.write_text(
+                "steps:\n  - uses: actions/checkout@main\n",
+                encoding="utf-8",
+            )
+            stdout = io.StringIO()
+            with redirect_stdout(stdout):
+                code = main(
+                    [
+                        tmp,
+                        "--format",
+                        "github-annotations",
+                        "--fail-on",
+                        "never",
+                    ]
+                )
+
+        self.assertEqual(code, 0)
+        self.assertEqual(
+            stdout.getvalue().strip(),
+            "::error file=ci.yml,line=2,title=floating-branch-ref::"
+            "Action is pinned to a mutable branch ref. Fix: Replace the branch "
+            "with a reviewed full commit SHA. uses: actions/checkout@main",
+        )
+
+    def test_github_annotations_output_is_empty_for_clean_workflow(self):
+        with tempfile.TemporaryDirectory() as tmp:
+            workflow = Path(tmp) / "safe.yml"
+            workflow.write_text(
+                "steps:\n"
+                "  - uses: actions/checkout@0123456789abcdef0123456789abcdef01234567\n",
+                encoding="utf-8",
+            )
+            stdout = io.StringIO()
+            with redirect_stdout(stdout):
+                code = main([tmp, "--format", "github-annotations"])
+
+        self.assertEqual(code, 0)
+        self.assertEqual(stdout.getvalue(), "")
+
 
 if __name__ == "__main__":
     unittest.main()