Skip to content

README.md

Latest commit

 

History

History
137 lines (99 loc) · 6.68 KB

README.md

File metadata and controls

137 lines (99 loc) · 6.68 KB
Raw

Scripts

This directory contains utility scripts for setting up and managing the gh-agentic-workflows pipeline.

org-history.js

Collects a deterministic JSON snapshot for one UTC calendar month (YYYY-MM) or ISO week (YYYY-Www) across an organization. The human-run monthly-org-history skill uses calendar-month snapshots to draft human-reviewed history/YYYY-MM.md interpretation. The plain weekly workflow commits immutable canonical evidence as history/YYYY-WW.json.

node scripts/org-history.js ORG 2026-W09 --output history/2026-09.json --bot 'bootc-bot[bot]'
node scripts/org-history.js ORG 2026-09 --output /tmp/ORG-2026-09-history.json --bot 'bootc-bot[bot]'
node scripts/org-history.js --previous-iso-week

Schema v5 retains the v4 period field names and changes detailed items: it contains only items with exact evidence linking them to a relevant workflow run with known AIC. Each record contains only repository, number, type, aic, and sorted, unique aicRunIds; generic GitHub metadata is intentionally omitted. aic is the normalized sum for its linked runs, including zero. A run linked exactly to multiple items contributes its full AIC to each association, so item AIC values are not additive; use coverage.aic.total for the organization-wide total. Repository aggregates still describe the full collected activity cohort, not just these AIC-linked detailed items; the linked run evidence is serialized for audit.

Pass --repo REPO to collect one non-archived, non-fork repository within ORG instead of the full visible organization. The resulting snapshot records the repository filter.

It requires authenticated gh and unzip. The snapshot is intentionally written to /tmp by default, not committed, and reports partial repository/artifact coverage. Current labels are snapshot state, not label history; explicit AI attribution markers are counted only on items created in the reported period. Output creation is exclusive: choose a new path rather than overwriting an existing snapshot.

--bot LOGIN additionally reads that bot's issue and PR conversation comments from the repository-wide comments endpoint. It uses a Generated by Actions-run footer as a fallback only when the run's retained usage artifact is unavailable. The displayed human-formatted agent and optional threat-detection AIC values are preserved and summed; a sole AIC value without a breakdown is the generated footer's run total, not an inferred zero threat-detection component. Artifacts remain authoritative. Hidden metadata only verifies run identity and is not an AIC source without a generated footer. Submitted PR review bodies currently have no such metadata, so they never become zero-AIC records. Comment history and usage artifacts are subject to bot visibility and GitHub retention limits.

install-labels.js

Installs the required labels on a repository for the issue → PR → review → fix → merge pipeline.

Labels Created

The script creates or updates the following labels:

  • agent/code (green) — Triggers the drafter agent. When applied to an issue, the drafter agent reads the issue, implements the change, validates it, and opens a pull request.

  • agent/fixme (red) — Applied by the review workflow when a PR needs work. The fix workflow consumes this label, reads the reviewer's feedback, and pushes a fix commit.

  • agent/lgtm (green) — Applied by the review workflow when a PR is approved and ready to merge. The merge workflow automatically merges PRs with this label.

  • agent/drafter-working, agent/review-working, agent/fix-working (yellow) — Indicates that the corresponding agent (drafter, review, or fix) is actively working on the issue or PR. Per-workflow labels avoid one workflow's cleanup clearing another's still-in-progress signal on the same PR.

  • agent/workflow-edits-allowed (purple) — Pre-authorizes an agent run to edit protected files (workflows, README, etc.) without triggering the request_review gate. Apply this to an issue before labeling it agent/code, or to a PR before applying agent/fixme.

Usage

Via GitHub Actions

The easiest way to install labels is using the included workflow. It also runs weekly on its own (the create-or-update loop is idempotent, so this just self-heals any label that gets renamed, deleted, or recolored by hand) — running it manually is only needed to create the labels immediately instead of waiting for the first scheduled run:

  1. Go to your repository's Actions tab
  2. Select the Install Labels workflow
  3. Click Run workflow

Alternatively, you can copy .github/workflows/install-labels.yml to your own repository and run it there. That workflow inlines the LABELS array and install loop directly in its actions/github-script step, so it has no dependency on this file being checked out.

Via github-script action

If you want to integrate label installation into your own workflow, install-labels.js is a plain CommonJS module you can require() after checking out the repo:

- uses: actions/checkout@v4
- name: Install gh-agentic-workflows labels
  uses: actions/github-script@v7
  with:
    script: |
      const { installLabels } = require('./scripts/install-labels.js');
      await installLabels(github, context);

Via GitHub CLI

You can also use the GitHub CLI to create the labels directly:

gh label create "agent/code" --color 0E8A16 \
  --description "Triggers the drafter agent"

gh label create "agent/fixme" --color D93F0B \
  --description "Reviewer agent found issues that need fixing"

gh label create "agent/lgtm" --color 0E8A16 \
  --description "Reviewer agent approved; ready to auto-merge"

gh label create "agent/drafter-working" --color FBCA04 \
  --description "The drafter agent is actively working on this issue"

gh label create "agent/review-working" --color FBCA04 \
  --description "The review agent is actively working on this PR"

gh label create "agent/fix-working" --color FBCA04 \
  --description "The fix agent is actively working on this PR"

gh label create "agent/workflow-edits-allowed" --color 5319E7 \
  --description "Pre-authorizes agent runs to edit protected files without the request_review gate"

Or via gh api, e.g. to update an existing label:

gh api repos/:owner/:repo/labels/agent/code -X PATCH \
  -f color="0E8A16" -f description="Triggers the drafter agent"

Customizing Labels

To customize the labels (change colors, descriptions, or add new ones), edit the LABELS array in install-labels.js and the matching copy in .github/workflows/install-labels.yml, then rerun the installation workflow to update the labels on your repository.