AGENTS.md β projectbluefin/actions#
Part of an agentic operating system, built by agentic workflows.
This repo is the canonical CI skills hub for the projectbluefin org. Every agent session here
compounds the knowledge of all future agents. See the org-wide operating model:
projectbluefin/.github/AGENTS.md
Shared composite GitHub Actions for bootc image builders (bluefin, aurora, bazzite).
Load docs/SKILL.md before modifying any action.
Before using any tool or library: look up its docs via Context7 first. Always.
GitHub Actions, bootc, cosign, skopeo, syft, oras, Trivy, Renovate β every tool has live, authoritative docs.
Pattern:resolve-library-idβget-library-docsβ implement β cite the section.
Guessing, flag-hunting, and trial-and-error are banned. The docs exist. Read them.
The System You Are Part Of#
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β KubeStellar Hive https://kubestellar.io/live/hive/bluefin/ β
β AI-native Continuous Maturity Model (ACMM) orchestration β
β Agents run at increasing autonomy levels β you are one of them β
ββββββββββββββββββββββββββ¬βββββββββββββββββββββββββββββββββββββββββ
β
ββββββββββββββββ΄βββββββββββββββ
βΌ βΌ
βββββββββββββββββββββββ ββββββββββββββββββββββββββββ
β bonedigger β β kubestellar-bot β
β (client + bot) β β (repo automation) β
β β β β
β ujust report β β Processes issues from β
β ββ agent collects ββββββΆβ bonedigger pipeline β
β system state β β Implements fixes, ships β
β humans can't β β improvements back to β
β ββ files issue to β β the image β
β image repo β β β
βββββββββββββββββββββββ ββββββββββββββββββββββββββββ
β² β
β β
ββββββββββββ ships ββββββββββββ
better OS β better bonedigger β loop
bonedigger (projectbluefin/bonedigger) is the
client + lifecycle bot. Users run ujust report β an agent collects system diagnostics, scrubs PII
on-device, and files an issue to the image repo. The bonedigger GitHub Actions lifecycle bot then
manages the pipeline: filed β approved β queued β claimed β done.
kubestellar-bot is the repo automation layer built on
KubeStellar Hive. It picks up queued issues,
dispatches agents to implement fixes and improvements, and ships them back.
You are an agent in this system. Your work compounds. Keep workflows deterministic and
repeatable for humans via Just.
The Self-Improvement Loop#
This is the core operating model. Read it before starting any task.
Every agent session here produces two outputs:
- The work β the PR, fix, or improvement.
- The learning β what you discovered that a future agent should know.
Output 1 without Output 2 leaves the system no smarter. The loop only compounds if agents write back.
Agent works on task
ββ discovers pattern / workaround / convention
ββ writes it to the relevant skill file
ββ commits in the same PR
ββ next agent starts smarter
ββ loop
Skill-improvement mandate β applies to every repo in this org#
Before marking your work complete / before requesting final review:
- Did I discover any workaround, non-obvious pattern, or convention?
- Is there a skill file for the area I worked in?
- If yes β did I update it?
- If no β did I create one?
- Is the skill file committed in this same PR?
For the full skill file format and where to write things, see the org-wide:
projectbluefin/.github/AGENTS.md
What counts as a learning worth writing back#
Write it:
- A workaround for an upstream bug (include component + issue link)
- A non-obvious pattern required for correctness
- A convention that isn't obvious from the code
- Something you had to discover by trial and error
Don't write it:
- One-off task notes ("use commit message X for this PR")
- Obvious things any developer would know
- Ephemeral state ("currently broken, fix pending")
Org pipeline β projectbluefin#
projectbluefin/actions βββ shared CI building blocks
β
βββ projectbluefin/bluefin (bootc desktop image, Path 1 β reusable-build.yml)
βββ projectbluefin/dakota (BST/BuildStream image, Path 2 β Γ la carte, deferred)
βββ ublue-os/aurora (Aurora desktop image)
βββ ublue-os/bazzite (Bazzite gaming image)
Path 1 (full reusable workflow): consumer calls reusable-build.yml@v1 and satisfies the Justfile contract. Used by bluefin and aurora.
Path 2 (Γ la carte composite actions): consumer calls individual actions. Used by dakota (BST build engine β create-release and sign-and-publish adopted; see issue #16 for remaining actions).
Actions are referenced as projectbluefin/actions/bootc-build/<name>@v1. Breaking changes to an action require a version bump and coordinated update across all consuming repos.
Release path: all consumer repos (bluefin, dakota) use bootc-build/create-release as the factory-standard release action. It reads the SPDX-JSON SBOM already produced by sign-and-publish/just sbom, diffs it against the previous release, renders a release card (light + dark PNG), and generates supply-chain release notes with CNCF verification instructions (cosign, oras, slsa-verifier).
Human Decision Points β Stop and Ask#
Agents implement autonomously except at these gates. Stop and request human input:
| Gate | When |
|---|---|
| Design Gate | Architecture changes, new subsystem design, behavioral changes visible to consumers |
| Security Gate | Auth, signing, supply chain, secrets handling, SHA pinning for security-critical actions |
| Breakage Gate | Cross-repo breaking changes β removing/renaming inputs, changing defaults that affect consuming repos |
| Merge Gate | PRs in projectbluefin/actions require a maintainer to merge. This is a prow managed repo. Image repo (bluefin, dakota) promotion PRs are fully automated β no human approval required. |
main is governed by a merge queue β never trust gh pr merge's exit code. Every
sanctioned merge path must go through the queue, agents and humans alike. Other paths
exist and will succeed β a direct REST merge skips the queue entirely, and --admin
overrides protection β which is exactly why using the queue has to be deliberate rather
than assumed. See docs/skills/merge-governance.md for the full procedure and for the
bypasses that look legitimate but are not:
gh pr merge --squashprints! The merge strategy for main is set by the merge queue
and exits 0, having enqueued the PR rather than merged it.- A re-run prints
! Pull request <repo>#<n> is already queued to mergeβ a different
string sharing no substring with the first β and also exits 0. - Plain
gh pr merge(queue strategy) enqueues with empty stderr and exit 0.
Never infer the outcome from exit status or stderr text. Confirm it:
gh pr view <n> --json state --jq .state # MERGED is conclusive; OPEN only means "not merged"
OPEN does not by itself mean the PR is queued β a blocked PR gets auto-merge armed
instead of a queue entry. Check mergeQueueEntry before claiming it is queued:
gh api graphql -f query='{repository(owner:"projectbluefin",name:"actions"){
pullRequest(number:<n>){ mergeQueueEntry{position state} autoMergeRequest{mergeMethod} }}}'
The same rule is encoded in reusable-renovate-automerge.yml; see
docs/skills/factory-operations.md β "Renovate" for the full gotcha list.
When in doubt, open a draft PR with your implementation and ask explicitly.
Verification β Agents Implement and Verify; Humans Approve Unless Authorized#
PRs require maintainer approval and merging under the repo's branch protection and prow management rules. Before merging, confirm the PR is not a draft or blocked, it is mergeable, and every required CI check is green. Do not merge a PR with failing, pending, or missing required checks β a missing required check disqualifies a merge exactly as a failing one does.
Do not request review without evidence. Before opening a PR for review:
- Link to a CI run, workflow run, or test output that exercises your change
- If no automated test exists, describe how you manually verified the change
- Skill file update must be committed in the same PR (not a follow-up)
Mandatory gates#
Read-first: Read AGENTS.md, docs/SKILL.md, and .github/copilot-instructions.md before touching any action.
Session hygiene (enforced): Reviews are read-only β never edit files during a review unless explicitly asked to fix. When asked to "review this PR" with a generic /pulls link, list open PRs and confirm the target; never review the local working tree as a substitute. End every session with a clean working tree β commit to a branch, stash with a message, or revert; stranded uncommitted changes mislead the next session. See docs/skills/session-hygiene.md.
Skill contribution (enforced): If you discover a pattern, fix a recurring mistake, or learn something that would help future agents β update the relevant file in docs/skills/ in the same PR as your change. If no skill file exists for the area, create one and add it to the routing table in docs/SKILL.md. Skills live here, not in per-agent configs.
Supply chain gates: Every action that downloads external files (Containerfiles, scripts, configs) at build time must vendor those files into the action directory or verify their SHA-256 before use. Never pass a mutable URL directly to buildah build or bash. See docs/skills/supply-chain.md for the full pattern, the chunkah Containerfile.splitter vendoring procedure, and the manifest-index-vs-platform-digest rule for OCI image pins. Routine chunkah upgrades are now fully automated via Renovate + vendor-chunka-files.yml β no manual steps required.
SHA pinning: Every third-party uses: is pinned to a full commit SHA with a version comment. Production first-party Actions references use managed @v1, not self-SHA pins. A reviewed first-party candidate branch is permitted only for the secret-free, read-only onboarding preview interface/runtime; switch that preview interface to @v1 after publication. Candidate source never grants production write authority.
Pre-commit guard: no-floating-action-tags blocks third-party @main/@v* floating action tags in workflow and composite action files. This repo's own @v1 refs in consumer repos are exempted from the guard in those repos β they are managed floating tags deliberately advanced by this repo's release process.
No breaking changes without a version signal: Removing or renaming an input, or changing default behavior, requires coordinating with consuming repos. Document the blast radius in the PR description.
Consumer validation (required before merging): For any action change, open a PR in at least one consuming repo (projectbluefin/bluefin is the primary) that uses @v1 on the affected workflows. CI must pass there before merging to main and advancing the @v1 tag. Note that a draft PR in bluefin produces no CI run β run gh pr ready <n> to get a citable run ID. The PR template's Consumer PR, Consumer CI run, and Out-of-org consumer impact fields are enforced by .github/workflows/consumer-validation.yml. See docs/skills/consumer-validation.md for the full protocol.
Consumer validation evidence: Consumer PR: and Consumer CI run: require actual matching URLs in projectbluefin/{bluefin,dakota,common,chairlift}. Only Out-of-org consumer impact: accepts N/A. Path-based non-consumer changes and bot-authored PRs retain the workflow's exemptions. For new issue-policy interfaces, exercise the candidate runtime in the real consumer's read-only preview before release; production remains @v1.
Consumer production references use @v1. Read-only first-party candidate preview is the bootstrap exception described above. Native merge and successful actual main CI drive the managed publisher; consumers activate only after the released-source guard passes.
Consumer repo branches: projectbluefin/bluefin uses testing as its active dev branch. When opening consumer validation PRs: target testing for bluefin. Never target main for bluefin β PRs opened there will need to be reverted.
gh run rerun preserves old workflow code. After a workflow fix, push a new feature-branch commit to trigger a fresh run; never bypass native reviews or queue controls to obtain a green result.
Skill files are procedures, not logs. docs/skills/ files must describe how to do things β patterns, commands, decision rules. Never record specific SHA hashes, PR numbers, current deployment status, or any point-in-time snapshot. Those become stale on the next commit and mislead future agents.
Verification: Every PR must confirm that the action change was exercised in a real workflow (link to a CI run or test job). No untested changes.
Agents MUST NOT push directly to main. All changes via PR from a feature branch. Branch protection enforces this; direct pushes are blocked for non-admins.
Managed @v1 publication: Native reviewed merge to main is followed by
the unfiltered Unit Tests and actionlint push workflows. update-v1-tag.yml
publishes only when both succeed at the current main commit; failed, missing,
pending or superseded CI leaves v1 unchanged. Inspect publisher evidence and
compare git ls-remote origin refs/heads/main refs/tags/v1 before activating
consumers. Do not force-tag around this gate. The lifecycle/Prow runtime
independently verifies source bytes and actual main CI before writes.
What this affects: every consumer workflow calling reusable-*.yml@v1 or bootc-build/*@v1 β currently bluefin and dakota. Changes take effect on the next workflow run in each repo; nothing is re-run automatically.
SBOM alignment: the factory standard is Syft β SPDX-JSON, attached via ORAS and stored as a GitHub Actions artifact. sign-and-publish handles this for Fedora-based images. BST/dakota uses just sbom (also SPDX-JSON). All release notes must be generated from these SBOMs β never from separate container inspection scripts.
Production promotion in consumer repos is fully automated. The environment: production gate on promotion/release workflows fires automatically once gate checks pass β no human approvals required. Admin bypasses are permanently logged in the Environment deployment history.
π« Absolute prohibition β ublue-os org#
NEVER create issues, pull requests, comments, forks, webhook calls, API writes, automated reports, or any other programmatic action targeting any ublue-os/* repository.
This applies in every situation, without exception:
- Issues, comments, PRs, forks β BANNED
- Automated reports (CI notifications, diagnostic uploads) β BANNED
workflow_dispatchorrepository_dispatchcalls toublue-os/*β BANNED- Any
ghCLI command that writes toublue-os/*β BANNED
If a task seems to require touching an upstream ublue-os repo β stop and tell the human to report it manually.
PR Comment Policy#
One comment per PR event, max. Combine all findings into a single comment.
Never duplicate GitHub UI state. Do not post CI pass/fail summaries or approval counts.
When in doubt, don't post. "Tests pass" = post nothing.
Development Standards#
Commit format (required)#
Conventional Commits: <type>(<scope>): <description>
Common types: feat fix docs ci refactor chore build
AI attribution (required on every commit)#
feat(actions): add container build optimization
Optimize multi-stage build to reduce image size.
Assisted-by: Claude Sonnet 4.6 via GitHub Copilot
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Both trailers are required when an AI agent authors or substantially revises a commit.
Knowledge routing#
All learnings go to docs/skills/ β never to .github/copilot-instructions.md (pointer-only wrapper, read-only), and never to a personal agent config outside this repo.
| You are working in... | Write to |
|---|---|
projectbluefin/actions | docs/skills/ |
| Any other projectbluefin repo | That repo's docs/skills/ (create if absent) |
| ublue-os repos (aurora, bazzite) | NEVER write to these repos β see prohibition above |
| Cross-cutting (affects multiple repos) | Local first, then open propagation issue in projectbluefin/actions |
After editing a skill file, commit it in the same PR as the triggering change.
Why: Skills in this repo are the canonical reference. Personal agent configs are ephemeral and siloed. A fix discovered here belongs to every future agent working in this repo β not just the one that found it.
Repositories#
Core repos in scope for this actions library#
| Repo | Role |
|---|---|
| projectbluefin/bluefin | Main OS image (Path 1 β reusable-build.yml) |
| projectbluefin/dakota | BuildStream image build (Path 2, partial adoption) |
| projectbluefin/actions | This repo β shared CI actions + canonical skills hub |
| ublue-os/aurora | KDE variant (Path 1, external β read-only) |
| ublue-os/bazzite | Gaming variant (external β read-only) |
Infrastructure#
| Repo | Role |
|---|---|
| projectbluefin/testsuite | QA pipeline β Argo + KubeVirt + AT-SPI |
| projectbluefin/bonedigger | Client reporting + issue lifecycle bot |
| projectbluefin/housekeeping | Org-wide maintenance workflows |
Build Tools#
- Just β command runner (
just build,just test,just validate,just sbom) - Podman / Buildah β container building and layer manipulation
- GitHub Actions β CI/CD via composite actions and reusable workflows
- Renovate β automated dependency updates (SHA pins, digest bumps) β inherits from projectbluefin/renovate-config
- cosign β keyless signing + attestation verification
- syft / oras β SBOM generation and OCI referrer attachment
- Trivy β CVE scanning before push