module · Code & DevOps

GitHub

Comprehensive GitHub control plane — orgs, repos, teams, issues, pull requests, branches & protection, Actions secrets/variables (names only), runners, app installations, code security, and Codespaces metadata. Snapshot/diff/apply round-trip across every safe resource kind.

Namespace: weave github Env: GITHUB_TOKEN

Commands

State kinds

Code & DevOps

Setup

Configure credentials via environment variables. We recommend sourcing them through 1Password or your secrets manager rather than committing them to the shell rc.

Official API reference

weave commands for this module are checked against the vendor's published API.

REST API

Variable	Description	Status
GITHUB_TOKEN	Required for authentication.	required
GITHUB_ORG	Default org login for org-scoped commands (saves --org on every call)	optional
GITHUB_API_URL	GitHub Enterprise Server REST root (defaults to https://api.github.com)	optional

Sanity-check the wiring:

weave secrets check
weave github --help
weave doctor   # reports GITHUB_TOKEN status

Capabilities

What this module can do, by entity and verb. ✓ means a working CLI surface; · means not (yet) wired.

Entity	find	list	show	do	snapshot	diff	apply
app-installation	·	✓	✓	·	✓	✓	·
block	·	✓	·	·	·	·	·
branch	✓	✓	·	·	·	·	·
branch-protection	·	·	✓	·	✓	✓	✓
codespaces-secret	·	✓	·	·	·	·	·
collaborator	·	✓	·	·	✓	✓	✓
custom-role	·	✓	·	·	·	·	·
environment	·	✓	✓	·	✓	✓	✓
invitation	·	·	·	✓	·	·	·
issue	·	✓	·	✓	·	·	·
issue-labels	·	·	·	·	✓	✓	✓
label	·	✓	·	·	·	·	·
member	·	✓	·	·	·	·	·
org	·	·	·	✓	·	·	·
org-actions-permissions	·	·	·	·	✓	✓	✓
org-actions-secrets-meta	·	·	·	·	✓	✓	✓
org-actions-variables	·	·	·	·	✓	✓	✓
org-settings	·	·	✓	·	✓	✓	✓
pull	✓	✓	·	✓	·	·	·
repo	✓	✓	·	✓	✓	✓	✓
repo-actions-permissions	·	·	·	·	✓	✓	✓
repo-actions-secrets-meta	·	·	·	·	✓	✓	✓
repo-actions-variables	·	·	·	·	✓	✓	✓
repo-security	·	·	✓	·	·	·	·
repo-topics	·	·	·	·	✓	✓	✓
runner	·	✓	·	·	·	·	·
runner-group	·	✓	·	·	✓	✓	✓
secret	·	✓	·	·	·	·	·
team	✓	✓	·	✓	✓	✓	✓
team-member	·	✓	·	·	·	·	·
team-memberships	·	·	·	·	✓	✓	✓
team-repos	·	·	·	·	✓	✓	✓
topic	·	✓	·	·	·	·	·
user	✓	·	·	·	·	·	·
user-key	·	✓	·	·	·	·	·
variable	·	✓	·	·	·	·	·
webhook	·	✓	·	·	✓	✓	✓
workflow	·	·	·	✓	·	·	·
workflow-run	·	✓	·	·	·	·	·

Commands

Every registered CLI command, grouped by verb. Each example uses placeholder arguments — substitute real values for your environment.

find (5)

find branch

read

Find a branch in a repo by name (--repo + name).

weave github find branch <name>

find pull

read

Find a pull request by owner/name#number.

weave github find pull <ref>

find repo

read

Find a repo by owner/name.

weave github find repo <full-name>

find team

read

Find a team by org/team-slug.

weave github find team <ref>

find user

read

Find a GitHub user by login.

weave github find user <login>

list (22)

list app-installations

read

List GitHub App installations on an org.

weave github list app-installations <arg>

list blocks

read

List users blocked by an organization.

weave github list blocks <arg>

list branches

read

List branches on a repo (paginated; --protected to filter).

weave github list branches <arg>

list codespaces-secrets

read

List Codespaces secrets (org or self; names only).

weave github list codespaces-secrets <arg>

list collaborators

read

List collaborators on a repo.

weave github list collaborators <arg>

list custom-roles

read

List org-level custom repository roles.

weave github list custom-roles <arg>

list environments

read

List deployment environments on a repo.

weave github list environments <arg>

list issues

read

List issues on a repo (paginated).

weave github list issues <arg>

list labels

read

List issue labels on a repo.

weave github list labels <arg>

list members

read

List members of an organization (paginated).

weave github list members <arg>

list pulls

read

List pull requests on a repo (paginated).

weave github list pulls <arg>

list repos

read

List repos for an org or user (paginated).

weave github list repos <arg>

list runner-groups

read

List Actions runner groups for an organization.

weave github list runner-groups <arg>

list runners

read

List self-hosted Actions runners (org or repo).

weave github list runners <arg>

list secrets

read

List Actions secrets (NAMES only — values are never returned by the API).

weave github list secrets <arg>

list team-members

read

List members of a team (--team org/slug).

weave github list team-members <arg>

list teams

read

List teams in an organization (paginated).

weave github list teams <arg>

list topics

read

List topics on a repo.

weave github list topics <arg>

list user-keys

read

List GPG + SSH keys for the authenticated user.

weave github list user-keys <arg>

list variables

read

List Actions variables (org, repo, or environment).

weave github list variables <arg>

list webhooks

read

List webhooks on a repo.

weave github list webhooks <arg>

list workflow-runs

read

List recent Actions workflow runs on a repo.

weave github list workflow-runs <arg>

show (5)

show app-installation

read

Show a GitHub App installation by id.

weave github show app-installation <install-id>

show branch-protection

read

Show branch protection rules on a single branch (--repo + branch).

weave github show branch-protection <branch>

show environment

read

Show a deployment environment (--repo + name).

weave github show environment <name>

show org-settings

read

Show organization settings (visibility, MFA, billing email, …).

weave github show org-settings <arg>

show repo-security

read

Show security features state for a repo.

weave github show repo-security <arg>

do (24)

do accept-invitation

write

Accept a repository invitation for the authenticated user.

weave github do accept-invitation <invitation-id>

do add-team-member

write

Add a user to a team (or upgrade to maintainer).

weave github do add-team-member <user>

do add-team-repo

write

Grant a team access to a repository.

weave github do add-team-repo <repo>

do archive-repo

write

Mark a repo as archived (read-only).

weave github do archive-repo <repo>

do block-user

write

Block a user at the organization level.

weave github do block-user <user>

do close-issue

write

Close an issue (owner/name#number).

weave github do close-issue <ref>

do close-pull

write

Close a pull request without merging.

weave github do close-pull <ref>

do decline-invitation

write

Decline a repository invitation for the authenticated user.

weave github do decline-invitation <invitation-id>

do delete-repo

write

Delete a repo permanently (irreversible).

weave github do delete-repo <repo>

do disable-vulnerability-alerts

write

Disable Dependabot vulnerability alerts on a repo.

weave github do disable-vulnerability-alerts <repo>

do disable-workflow

write

Disable an Actions workflow by id (--repo + id).

weave github do disable-workflow <workflow-id>

do enable-vulnerability-alerts

write

Enable Dependabot vulnerability alerts on a repo.

weave github do enable-vulnerability-alerts <repo>

do enable-workflow

write

Re-enable an Actions workflow by id.

weave github do enable-workflow <workflow-id>

do label-issue

write

Replace labels on an issue.

weave github do label-issue <ref>

do merge-pull

write

Merge a pull request (owner/name#number).

weave github do merge-pull <ref>

do remove-team-member

write

Remove a user from a team.

weave github do remove-team-member <user>

do remove-team-repo

write

Revoke a team's access to a repository.

weave github do remove-team-repo <repo>

do reopen-issue

write

Reopen a previously-closed issue.

weave github do reopen-issue <ref>

do reopen-pull

write

Reopen a previously-closed pull request.

weave github do reopen-pull <ref>

do rerun-workflow

write

Re-run an Actions workflow run by id.

weave github do rerun-workflow <run-id>

do set-default-branch

write

Change a repo's default branch.

weave github do set-default-branch <repo>

do transfer-repo

write

Transfer a repo to a new owner.

weave github do transfer-repo <repo>

do unarchive-repo

write

Restore an archived repo to writable.

weave github do unarchive-repo <repo>

do unblock-user

write

Unblock a user at the organization level.

weave github do unblock-user <user>

watch (1)

watch pr-status

write

Poll a PR until it merges, closes, or times out.

weave github watch pr-status <ref>

snapshot / diff / apply are generated automatically from the State Kinds declared on this module — see the State kinds section below for per-kind details. Workflow: snapshot → edit YAML → diff → apply --yes (or confirm interactively; apply --dry-run previews the same diff).

State kinds

Resources this module can snapshot and diff; apply where the kind supports live writes (see Round-trip per kind). Always run diff before apply; use --yes in automation after review. Files live under .weave-state/github/.

branch-protection

snapshot diff apply

Branch protection rules on every protected branch of a repo (full apply).

Scope: repo
Round-trip: Full round-trip — snapshot, diff, apply.

State file skeleton

module: github
kind: branch-protection
repo: <value>
items:
  - # <fields specific to this kind — see snapshot output>

org-settings

snapshot diff apply

Organization-wide policy knobs (member perms, repo defaults, signoff) (full apply).

Scope: org
Round-trip: Full round-trip — snapshot, diff, apply.

State file skeleton

module: github
kind: org-settings
org: <value>
items:
  - # <fields specific to this kind — see snapshot output>

repos

snapshot diff apply

Per-org repo inventory + writable knobs (visibility, merge flags, topics) (apply: updates only).

Scope: org
Round-trip: Full round-trip — snapshot, diff, apply.

State file skeleton

module: github
kind: repos
org: <value>
items:
  - # <fields specific to this kind — see snapshot output>

collaborators

snapshot diff apply

Direct collaborators on a repo + their permission level (full apply).

Scope: repo
Round-trip: Full round-trip — snapshot, diff, apply.

State file skeleton

module: github
kind: collaborators
repo: <value>
items:
  - # <fields specific to this kind — see snapshot output>

repo-topics

snapshot diff apply

Topic strings on a repo (full apply via /topics).

Scope: repo
Round-trip: Full round-trip — snapshot, diff, apply.

State file skeleton

module: github
kind: repo-topics
repo: <value>
items:
  - # <fields specific to this kind — see snapshot output>

webhooks

snapshot diff apply

Repository webhooks keyed by config URL (full apply).

Scope: repo
Round-trip: Full round-trip — snapshot, diff, apply.

State file skeleton

module: github
kind: webhooks
repo: <value>
items:
  - # <fields specific to this kind — see snapshot output>

environments

snapshot diff apply

Deployment environments + wait timer + required reviewers (full apply).

Scope: repo
Round-trip: Full round-trip — snapshot, diff, apply.

State file skeleton

module: github
kind: environments
repo: <value>
items:
  - # <fields specific to this kind — see snapshot output>

teams

snapshot diff apply

Every team in an org with privacy/permission/description (full apply).

Scope: org
Round-trip: Full round-trip — snapshot, diff, apply.

State file skeleton

module: github
kind: teams
org: <value>
items:
  - # <fields specific to this kind — see snapshot output>

team-memberships

snapshot diff apply

Every login + role inside a single team (full apply).

Scope: team
Round-trip: Full round-trip — snapshot, diff, apply.

State file skeleton

module: github
kind: team-memberships
team: <value>
items:
  - # <fields specific to this kind — see snapshot output>

team-repos

snapshot diff apply

Every repo a team has access to + permission (full apply).

Scope: team
Round-trip: Full round-trip — snapshot, diff, apply.

State file skeleton

module: github
kind: team-repos
team: <value>
items:
  - # <fields specific to this kind — see snapshot output>

issue-labels

snapshot diff apply

Issue labels on a repo (full apply).

Scope: repo
Round-trip: Full round-trip — snapshot, diff, apply.

State file skeleton

module: github
kind: issue-labels
repo: <value>
items:
  - # <fields specific to this kind — see snapshot output>

org-actions-permissions

snapshot diff apply

Org-level Actions enablement + allowed actions policy (full apply).

Scope: org
Round-trip: Full round-trip — snapshot, diff, apply.

State file skeleton

module: github
kind: org-actions-permissions
org: <value>
items:
  - # <fields specific to this kind — see snapshot output>

repo-actions-permissions

snapshot diff apply

Per-repo Actions enablement + allowed actions policy (full apply).

Scope: repo
Round-trip: Full round-trip — snapshot, diff, apply.

State file skeleton

module: github
kind: repo-actions-permissions
repo: <value>
items:
  - # <fields specific to this kind — see snapshot output>

repo-actions-variables

snapshot diff apply

Per-repo Actions variables — plaintext values are round-tripped (full apply).

Scope: repo
Round-trip: Full round-trip — snapshot, diff, apply.

State file skeleton

module: github
kind: repo-actions-variables
repo: <value>
items:
  - # <fields specific to this kind — see snapshot output>

org-actions-variables

snapshot diff apply

Org-level Actions variables — plaintext values are round-tripped (full apply).

Scope: org
Round-trip: Full round-trip — snapshot, diff, apply.

State file skeleton

module: github
kind: org-actions-variables
org: <value>
items:
  - # <fields specific to this kind — see snapshot output>

runner-groups

snapshot diff apply

Org-level Actions runner groups (name + visibility apply; default group preserved).

Scope: org
Round-trip: Full round-trip — snapshot, diff, apply.

State file skeleton

module: github
kind: runner-groups
org: <value>
items:
  - # <fields specific to this kind — see snapshot output>

repo-actions-secrets-meta

snapshot diff apply

Per-repo Actions secret NAMES + timestamps. Secrets are tracked by name only — apply can DELETE by name, never create/update values.

Scope: repo
Round-trip: Full round-trip — snapshot, diff, apply.

State file skeleton

module: github
kind: repo-actions-secrets-meta
repo: <value>
items:
  - # <fields specific to this kind — see snapshot output>

org-actions-secrets-meta

snapshot diff apply

Org-level Actions secret NAMES + timestamps. Secrets are tracked by name only — apply can DELETE by name, never create/update values.

Scope: org
Round-trip: Full round-trip — snapshot, diff, apply.

State file skeleton

module: github
kind: org-actions-secrets-meta
org: <value>
items:
  - # <fields specific to this kind — see snapshot output>

app-installations

snapshot diff apply

Installed GitHub Apps on the org + selected repos (snapshot+diff only — installs require an OAuth flow that's not roundtrippable).

Scope: org
Round-trip: Snapshot + diff (apply not wired).

State file skeleton

module: github
kind: app-installations
org: <value>
items:
  - # <fields specific to this kind — see snapshot output>

Workflows

End-to-end recipes from operators who already run this module in production. Copy, adapt, and put under change-control.

Onboard a new team

Create the team, add members, attach repos — all in one transaction.

weave github do add-team-member alice --team acme/platform --role maintainer --yes
weave github do add-team-member bob   --team acme/platform --yes
weave github do add-team-repo  acme/api    --team acme/platform --permission push --yes
weave github do add-team-repo  acme/infra  --team acme/platform --permission admin --yes
weave github snapshot team-memberships --team acme/platform
git add .weave-state/github && git commit -m 'onboard platform team'

Quarterly access audit

Snapshot collaborators on every repo and team memberships, commit to git, diff next quarter.

weave github list repos --org acme --json | jq -r '.[].repo' > /tmp/repos
while read r; do weave github snapshot collaborators --repo $r; done < /tmp/repos
weave github list teams --org acme --json | jq -r '.[].slug' | 
  xargs -I{} weave github snapshot team-memberships --team acme/{}
git add .weave-state/github && git commit -m 'access audit Q1'
# next quarter:
while read r; do weave github diff collaborators --repo $r; done < /tmp/repos

Lockdown after a security incident

Inventory every webhook on every repo, review by hand, snapshot, revoke.

weave github list webhooks --repo acme/api
weave github snapshot webhooks --repo acme/api
$EDITOR .weave-state/github/acme/api/webhooks.yaml   # delete the rogue entry
weave github diff webhooks --repo acme/api
weave github apply webhooks --repo acme/api --yes

Migrate a repo to archived

Snapshot protections first so reversal is one diff away.

weave github show branch-protection main --repo acme/legacy
weave github snapshot branch-protection --repo acme/legacy
git add .weave-state/github && git commit -m 'pre-archive snapshot'
weave github do archive-repo acme/legacy --yes

Roll out branch protection across a fleet of repos

Capture canonical rules from one repo, copy YAML to others, apply.

weave github snapshot branch-protection --repo acme/canonical
cp .weave-state/github/acme/canonical/branch-protection.yaml \
   .weave-state/github/acme/api/branch-protection.yaml
# update scope: repo + branches array in the new file
weave github diff  branch-protection --repo acme/api
weave github apply branch-protection --repo acme/api --yes

Watch a PR through merge

Long-poll a release PR — exits 0 when merged, 2 on timeout.

weave github find pull acme/api#1234
weave github watch pr-status acme/api#1234 --interval 30 --timeout 3600

Terraform parity

For each Terraform resource in the canonical provider, here's the equivalent live-API verb in weave. Use this as a migration cheat-sheet, not a 1:1 contract — weave deliberately stays in the live-state lane, not the desired-state lane.

Terraform resource	weave equivalent
github_organization_settings	weave github show org-settings / snapshot org-settings
github_organization_security_manager	weave github list custom-roles / list teams Custom-role admins are managed through team membership in weave.
github_organization_block	weave github list blocks / do block-user / do unblock-user
github_organization_custom_role	weave github list custom-roles Read-only — custom-role write API is GA but currently UI-only in weave.
github_repository	weave github find/list repo + do archive-repo/unarchive-repo/transfer-repo/delete-repo / snapshot repos
github_repository_collaborator(s)	weave github list collaborators / snapshot collaborators
github_repository_environment	weave github list environments / show environment / snapshot environments
github_repository_environment_deployment_policy	Tracked inside the environment record's deployment_branch_policy
github_repository_pull_request	weave github find pull / list pulls / do merge-pull/close-pull/reopen-pull / watch pr-status
github_repository_topics	weave github list topics / snapshot repo-topics
github_repository_webhook	weave github list webhooks / snapshot webhooks
github_repository_file	Not exposed — file content lives in git, not state YAML Use git, not weave.
github_repository_autolink_reference	Not exposed yet Planned for a future phase if demand surfaces.
github_team	weave github find/list team / snapshot teams
github_team_members / github_team_membership	weave github list team-members / do add-team-member/remove-team-member / snapshot team-memberships
github_team_repository	weave github do add-team-repo/remove-team-repo / snapshot team-repos
github_team_settings	Notification + privacy fields live in `teams` state kind
github_issue / github_issue_label	weave github list issues / do close-issue/reopen-issue/label-issue / snapshot issue-labels
github_branch / github_branch_default	weave github list branches / find branch / do set-default-branch
github_branch_protection	weave github show branch-protection / snapshot branch-protection
github_actions_secret / github_actions_organization_secret	weave github list secrets / snapshot {repo,org}-actions-secrets-meta Secret VALUES are never round-tripped. Snapshot tracks name + timestamps only; apply can DELETE by name.
github_actions_variable / github_actions_organization_variable	weave github list variables / snapshot {repo,org}-actions-variables Variables ARE round-tripped (they're plaintext by design).
github_actions_organization_permissions / github_actions_repository_permissions	weave github snapshot org-actions-permissions / repo-actions-permissions
github_actions_environment_secret	weave github list secrets --repo --environment Snapshot for env-scoped secrets is on the roadmap; list works today.
github_actions_runner_group(_repositories)	weave github list runner-groups / snapshot runner-groups
github_app_installation_repositories	weave github list app-installations / show app-installation / snapshot app-installations Read-only — install lifecycle requires OAuth flow.
github_repository_dependabot_security_updates / github_repository_vulnerability_alerts	weave github show repo-security / do enable-vulnerability-alerts / do disable-vulnerability-alerts
github_codespaces_*_secret	weave github list codespaces-secrets (names only) Like Actions secrets — values never round-tripped.
github_user_gpg_key / github_user_ssh_key	weave github list user-keys (read for self)
github_user_invitation_accepter	weave github do accept-invitation / do decline-invitation
(workflow runs / re-runs / watch pr-status)	weave github list workflow-runs / do rerun-workflow / watch pr-status Operational verbs unique to weave — no Terraform equivalent.

Troubleshooting & source

Missing credentials

Run weave doctor — it reports which env vars (including GITHUB_TOKEN) are set and which are blank.

Unexpected behaviour from a state apply

Re-run weave github diff <kind> to confirm the controller's current state, then re-snapshot before the next apply. The driver always re-snapshots before diffing.

Open the source

The module lives at https://github.com/andy-broyles/weavewhatever/tree/main/src/weave/modules/github. File a bug or feature request at https://github.com/andy-broyles/weavewhatever/issues.