Skip to content

docs: define reusable workflow interface guidance #24

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
xnoto merged 2 commits into from
Aug 28, 2026
Merged

docs: define reusable workflow interface guidance #24

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
4bd7d23
docs: define reusable workflow interface guidance
xnoto Aug 28, 2026
e313bcb
chore: remove obsolete local OpenCode overlay
xnoto Aug 28, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
96 changes: 3 additions & 93 deletions AGENTS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,97 +1,7 @@
# Agent Instructions

## Repository Purpose
This repository owns reusable GitHub Actions workflows for Make IT Work Cloud. Treat workflow inputs, permissions, runner labels, triggers, emitted checks, and artifacts as a public interface to all callers.

This repository contains reusable GitHub Actions workflows for the `makeitworkcloud` organization.
`opentofu.yml` runs on the `arc-tf` runner pod, whose image is owned by `images/tfroot-runner`; do not add a nested job container. The canonical pre-commit configuration is owned by that image repository and is fetched at CI time.

## Contribution Workflow

Use a branch and pull request for all changes. Do not push directly to `main`,
and do not push any branch unless explicitly requested.

## Key Workflows

### opentofu.yml

Reusable workflow for OpenTofu/Terraform root module repositories (`tfroot-*`). It:

1. Fetches the canonical pre-commit config from `makeitworkcloud/images`
2. Runs OpenTofu initialization and pre-commit without AWS or SSH credentials on the `arc-tf` runner pod (which is itself the `tfroot-runner` image - no nested `container:` block)
3. Runs a credentialed plan only for same-repository pull requests; fork pull requests run only the uncredentialed test job
4. Posts available plan output as a PR comment, reports a plan failure in that comment, and then fails the plan job
5. Applies on any push to `main` after the test and configured environment gates pass

**Pre-commit configuration is centralized** in `makeitworkcloud/images/tfroot-runner/pre-commit-config.yaml`. Do not add `.pre-commit-config.yaml` to individual tfroot repos.

### Workflow Inputs

| Input | Default | Description |
|-------|---------|-------------|
| `runs-on` | `arc-tf` | Runner label — the in-cluster ARC scale set whose pods run the tfroot-runner image |
| `setup-ssh` | `false` | Provision an SSH key + known_hosts for libvirt-style root modules |
| `environment` | `production` | Environment for the apply job |
| `aws-region` | `us-west-2` | AWS region for SOPS KMS access |
| `aws-role-to-assume` | `arn:aws:iam::332355796717:role/github-actions-sops-kms` | IAM role assumed via GitHub OIDC for SOPS KMS decrypt/encrypt |
| `gcp-workload-identity-provider` | empty | Google Workload Identity Provider resource name; when set, it replaces AWS authentication |
| `gcp-service-account` | empty | Google service account to impersonate through Workload Identity Federation |

The test job has only `contents: read` permission and does not receive cloud or SSH credentials. The plan job has `contents: read`, `id-token: write`, and `pull-requests: write`; the apply job has `contents: read` and `id-token: write`. Caller workflows must grant the permissions needed by credentialed plan and apply jobs. By default, SOPS decryption for `tfroot-*` repos uses AWS KMS via OIDC; do not pass `SOPS_AGE_KEY` to this workflow. Set both GCP inputs to use Google Workload Identity Federation instead.

There is no `container` input. The `arc-tf` runner pod IS the image, so adding `container:` on top would nest a container inside a container — don't do it.

### _dependabot-notify.yml

Reusable workflow that posts a synthetic alert to the cluster Alertmanager
(kube-prometheus-stack, exposed as `alertmanager.makeitwork.cloud` behind a
path-scoped Cloudflare Access app) when a caller repo's `pull_request` event
actor is `dependabot[bot]`. Callers are managed centrally by `tfroot-github`
(`.github/workflows/dependabot-notify.yml` in each repo, `secrets: inherit`).

The reusable lives at the underscore-prefixed path because `tfroot-github`
manages `.github/workflows/dependabot-notify.yml` as the caller in every
repository, including this one — anything at the non-prefixed path here is
overwritten on the next tfroot-github apply.

Requires the `CLOUDFLARE_AUTH_CLIENT_ID` / `CLOUDFLARE_AUTH_CLIENT_SECRET`
Actions secrets in the caller repository (the "GitHub Actions" Cloudflare
Access service token, distributed by `tfroot-github`). Alertmanager itself
has no auth; the Access app is the only gate. No checkout and no
`GITHUB_TOKEN` permissions are needed.

## Failure Modes

### "manifest unknown" or image pull failures

The `tfroot-runner` image is missing or the tag is wrong. Check:
1. Did the `images` repo `buildah` workflow succeed for the latest commit?
2. Is the runner template image tag in `kustomize-cluster/workloads/arc/arc-tf-application.yaml` resolvable on GHCR (`ghcr.io/makeitworkcloud/tfroot-runner:latest`)?

### Pre-commit hook failures

If hooks fail with missing tools or config mismatches:
1. Verify the canonical config in `images/tfroot-runner/pre-commit-config.yaml`
2. Rebuild `tfroot-runner` image if hooks were added/updated

### Checks never appear on a PR

No checks at all (not even pending) means workflow runs were never created.
Confirm with `gh run list --repo <repo> --branch <branch>` and by checking
check-runs on the head SHA. Zero runs of every event type across the org's
repos — especially when earlier PRs triggered normally — indicates a GitHub
Actions event-delivery incident, not a workflow configuration problem. Check
https://www.githubstatus.com before editing workflow files to "fix" it.
Recover by closing and reopening the PR (`reopened`) or force-pushing the
branch (`synchronize`); both are trigger types in these workflows.

### dependabot-notify shows `skipped` on human PRs

Expected. The notify job requires `github.actor == 'dependabot[bot]'`; on
human-authored PRs the caller workflow runs and the job skips. A skipped
notify job is not a failure — but `gh run watch --exit-status` treats a run
whose jobs all skipped as unsuccessful, so watch the `ci`/`opentofu` run when
validating a PR.

## Related Repositories

- `images` - Contains `tfroot-runner` image and canonical pre-commit config
- `tfroot-cloudflare`, `tfroot-libvirt`, `tfroot-github`, `tfroot-aws` - Terraform root module repos that consume this workflow
Use GitHub MCP to identify callers, inspect checks, and diagnose Actions delivery. Do not use local `gh` commands or dispatch/re-run workflows without explicit confirmation. A change must preserve uncredentialed fork validation, same-repository plan behavior, and environment-gated apply behavior unless the user explicitly requests a contract change.
39 changes: 0 additions & 39 deletions opencode.json
View file
Open in desktop

This file was deleted.