Legacy GitHub Actions setup

In the original AgentMachinist workflow, GitHub issues start Tasks, each Spec arrives as a draft pull request, and a runner on your machine executes approved work. It's still supported.

Starting fresh? The first-run guide covers the local workflow, which needs no GitHub setup and can still publish a pull request when you're ready. In this workflow, github.spec_source: local still means GitHub-backed work: your machine writes the Spec, then pushes it as a draft PR.

Who owns each step.

LEGACY GITHUB

Actions writes the Spec; your runner executes

Labeled issueGitHub Actionsadapter writes spec Approvalexact SHA Local runnerExecute; Review if on Ready PRyou review github.spec_source: github-actions

Set up and run it

  1. Use machinist onboard --setup-pr --spec-source github-actions to commit and push managed setup changes and open a draft setup PR.
  2. Managed workflows install the selected Spec adapter and use its declared repository secret. github.spec_install: pypi pins the published controller version; checkout is for its own development repository.
  3. Review and merge setup first. Then run machinist doctor --run-gates to verify default-branch deployment.
  4. Actions generates Specs and records trusted Approval. A local runner or watcher owns Execute and optional legacy Review. You merge the resulting PR yourself.

Adopt it, then run each Task.

The supported GitHub workflow uses issues, draft PR Specs, workflow-authored Approval, and a local Execute runner. Numeric issue IDs and local T1 IDs are separate.

onboard --setup-pr performs setup preflight, commits and pushes managed changes, and opens or reuses a draft setup PR. A retry preserves valid settings and resumes managed-only setup work; unrelated branch history is rejected.

terminal / legacy GitHub setup
machinist onboard --setup-pr --spec-source github-actions

Add the repository secret declared by your selected Spec adapter. Review and merge the setup PR before checking the deployed default-branch workflows:

terminal / verify merged GitHub setup
machinist doctor --run-gates

Create a GitHub Task by answering five terminal prompts: Objective, Acceptance criteria, Constraints, Verification, and optional Context. To supply an existing Markdown body instead, add --body-file ../task.md.

terminal / create a GitHub Task
machinist task new --title "Add CSV export for filtered transaction rows" --dispatch

Available since 0.16.0: issue creation prints the next activity and a sample command for the configured Spec source. In GitHub Actions mode, follow machinist explain 42 while the Spec is generated. In legacy local Spec mode, an undispatched issue suggests machinist spec 42; a dispatched issue suggests machinist watch --once -v, which can process other eligible queued Tasks too.

Wait for Actions to create its Spec PR, then read the Spec. Issue 42 and PR 18 below are illustrative; use the numbers returned for your Task.

terminal / request GitHub Approval
machinist approve --issue 42
# Or target its PR explicitly: machinist approve --pr 18

Stop here and wait for the approval workflow to complete successfully. The CLI requests Approval asynchronously; it does not mint trusted Evidence. Confirm the configured approval label is on the draft PR, then inspect the full commit identities:

terminal / check GitHub Approval Evidence
machinist inspect 42 --json

In the github_pr source, approval_sha must equal head_sha. If Approval is missing, stale, or the workflow failed, resolve that before executing. An early run can create a failed Execute attempt that requires explicit retry. Once the current Spec has trusted Approval, run:

terminal / execute the approved GitHub Spec
machinist run 42

Only if legacy review.enabled: true is configured, run independent Review after Execute succeeds:

terminal / optional GitHub Review
machinist review 42

The managed workflow checks write or admin access and the current head before recording its trusted SHA marker. To request Approval from GitHub instead of the CLI, post the PR-body command /machinist-execute <full-spec-commit-sha> as a PR comment. GitHub’s review Approve button is not this Gate.

A label without trusted Evidence is approval pending; a changed head is approval stale. With legacy Review enabled, Execute leaves the PR draft until independent Review completes. Findings remain advisory. With Review disabled, Execute can mark it ready after verification. You perform the remote merge.

If you used init or onboard without --setup-pr, commit setup manually: inspect the generated file list and stage selected files. Setup adds /.machinist/runs/ to .gitignore, so Task Run records stay out of the commit. Stage the Approval workflow with git add -- .github/workflows/machinist-approve.yml. With github.spec_source: github-actions, also run git add -- .github/workflows/machinist-spec.yml. When switching Spec modes or disabling workflow management, stage any removed managed workflow path shown by git status --short with git add -- <path>. Omit the workflow commands when no managed workflow files were generated or removed. Review the full staged diff with git diff --cached, then git commit and git push before the full doctor check.

Choose the recovery action matching the Task’s state; these are alternatives:

  • Revise a draft Spec: machinist spec 42 --revise.
  • Abandon the Task and close its Spec PR: machinist spec 42 --abandon --reason "requirements changed".
  • Retry failed Execute with retained edits: machinist retry 42 --phase execute --run --resume.
  • Retry failed Execute from a fresh Workshop: machinist retry 42 --phase execute --run --fresh.

Legacy Execute recovery defaults to fresh; local retry --task T1 defaults to resume. In legacy github.spec_source: local mode, use machinist spec 42 or watch for Spec generation. It still requires GitHub Approval workflows. See the GitHub setup reference and operator runbook for watcher services, labels, and recovery.

When setup stops.

Existing GitHub adoption stopped

Rerun machinist onboard --setup-pr to resume managed setup work and reuse its draft PR. Existing valid settings are preserved; change them with machinist config set. Merge setup before checking deployed default-branch workflows.

machinist doctor --run-gates

GitHub-specific diagnostics remain available: machinist doctor --run-gates, machinist sync-labels [--check|--apply], and machinist sync-workflows --check. These are not prerequisites for a local-only Task.