tools/github/operations.md - airflow-steward - Git at Google

 <!-- START doctoc generated TOC please keep comment here to allow auto update -->
 <!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
 **Table of Contents**  *generated with [DocToc](https://github.com/thlorenz/doctoc)*

 - [GitHub — CLI and API operation catalogue](#github--cli-and-api-operation-catalogue)
   - [Authentication](#authentication)
   - [Collaborator lookup (security-team roster)](#collaborator-lookup-security-team-roster)
   - [Issues](#issues)
     - [Read](#read)
     - [Create](#create)
     - [Edit — labels](#edit--labels)
     - [Edit — assignees](#edit--assignees)
     - [Edit — body](#edit--body)
     - [Comment](#comment)
     - [Close / reopen](#close--reopen)
   - [Milestones](#milestones)
     - [List](#list)
     - [Create](#create-1)
     - [Assign to an issue](#assign-to-an-issue)
   - [Labels](#labels)
     - [List](#list-1)
     - [Create](#create-2)
   - [Pull requests](#pull-requests)
     - [Create (public PR on the upstream repo)](#create-public-pr-on-the-upstream-repo)
     - [Edit — backport / other labels](#edit--backport--other-labels)
     - [Cross-link from the public PR back to the private tracker](#cross-link-from-the-public-pr-back-to-the-private-tracker)
   - [GraphQL (Projects V2)](#graphql-projects-v2)
   - [Error handling](#error-handling)

 <!-- END doctoc generated TOC please keep comment here to allow auto update -->

 <!-- SPDX-License-Identifier: Apache-2.0
      https://www.apache.org/licenses/LICENSE-2.0 -->

 # GitHub — CLI and API operation catalogue

 Shared reference for the `gh` CLI and `gh api` / `gh api graphql`
 invocations the skills use against the project's tracker repository.
 The skills reference this file for the recipe shape; each inline
 command in a skill already substitutes the tracker repo slug from the
 adopting project's manifest (see
 [`../../<project-config>/project.md`](../../<project-config>/project.md#repositories)).

 Placeholder convention used below:

 - `<tracker>` — the tracker repository slug from
   `<project manifest>.tracker_repo` (for Airflow, `<tracker>`).
 - `<upstream>` — the upstream codebase slug from
   `<project manifest>.upstream_repo` (for Airflow, `<upstream>`).
 - `<N>` — issue or PR number.

 ## Authentication

 Every skill's Step 0 pre-flight must verify that `gh` is authenticated
 and has collaborator access to `<tracker>`:

 ```bash
 gh auth status                          # must show logged-in user + scopes
 gh api repos/<tracker> --jq .name       # must return the repo name; 401/403/404 means stop
 ```

 A non-zero exit on either command is a hard stop — the skill reports
 the failure and asks the user to `gh auth login` (or to ask for
 collaborator access to the tracker) rather than retrying.

 ## Collaborator lookup (security-team roster)

 ```bash
 gh api repos/<tracker>/collaborators --jq '.[].login'
 ```

 The authoritative "who is on the security team" list. Every
 collaborator counts regardless of permission level (read / triage /
 write / maintain / admin). Roster snapshots maintained in the project
 manifest files (for Airflow, [`release-trains.md`](../../<project-config>/release-trains.md#security-team-roster))
 are caches of this command's output and can drift between changes.

 ## Issues

 ### Read

 ```bash
 gh issue view <N> --repo <tracker> \
   --json number,title,state,body,labels,milestone,assignees,author
 ```

 Add `--json comments` when the skill needs the comment trail, and
 `--json projectItems` when it needs to see which project boards the
 issue sits on.

 ### Create

 ```bash
 gh issue create --repo <tracker> \
   --title '<title>' \
   --body-file <path> \
   --label '<label-1>' --label '<label-2>'
 ```

 Always write the body to a temp file and pass `--body-file` — shell
 quoting silently corrupts anything with literal backticks, `$(…)`, or
 newlines inside a multi-paragraph body.

 ### Edit — labels

 ```bash
 gh issue edit <N> --repo <tracker> \
   --add-label '<label-a>,<label-b>' \
   --remove-label '<label-c>'
 ```

 Apply every add + remove in **one** call so the change lands as a
 single audit-trail entry rather than as N separate events.

 ### Edit — assignees

 ```bash
 gh issue edit <N> --repo <tracker> --add-assignee @me         # self-assign
 gh issue edit <N> --repo <tracker> --add-assignee <handle>    # named user
 ```

 ### Edit — body

 ```bash
 gh issue edit <N> --repo <tracker> --body-file <tmpfile>
 ```

 Write the edited body to a temp file first. The skills that perform
 "body-field surgery" (updating one `### <field>` section without
 touching the rest) read the full body, replace the targeted section
 between its header and the next `### ` heading, and write the result
 back via `--body-file`.

 ### Comment

 ```bash
 gh issue comment <N> --repo <tracker> --body-file <tmpfile>
 ```

 Before posting, **scrub the comment body for bare-name mentions** of
 project maintainers / release managers / security-team members and
 replace with `@`-handles. See the per-project mention rule (for
 Airflow, [`../../<project-config>/naming-conventions.md#mentioning-airflow-maintainers-and-security-team-members`](../../<project-config>/naming-conventions.md#mentioning-airflow-maintainers-and-security-team-members))
 for the grep-list of names to check.

 ### Close / reopen

 ```bash
 gh issue close <N>  --repo <tracker> --reason completed   # or 'not planned'
 gh issue reopen <N> --repo <tracker>
 ```

 ## Milestones

 ### List

 ```bash
 gh api 'repos/<tracker>/milestones?state=all&per_page=100' \
   --jq '.[] | select(.title == "<target>") | {number, state}'
 ```

 ### Create

 ```bash
 gh api repos/<tracker>/milestones \
   -f title='<target>' \
   -f state=open \
   -f description='<optional one-line description>'
 ```

 The create call returns the milestone object including its `number` —
 capture that in case the milestone is later closed (see fallback
 below).

 ### Assign to an issue

 ```bash
 gh issue edit <N> --repo <tracker> --milestone '<title>'
 ```

 **Closed-milestone fallback.** `gh issue edit --milestone '<title>'`
 fails with `'<title>' not found` if the milestone is closed. Fall back
 to the REST API and reference it by number:

 ```bash
 gh api repos/<tracker>/issues/<N> -X PATCH -F milestone=<number>
 ```

 ## Labels

 ### List

 ```bash
 gh label list --repo <tracker> --limit 100 \
   --json name,description,color --jq '.[].name'
 ```

 ### Create

 ```bash
 gh label create '<name>' --repo <tracker> \
   --description '<short description>' \
   --color '<hex>'
 ```

 Do **not** silently create labels without asking the user. Label
 names are the shared vocabulary of the security team, and new labels
 should be discussed.

 ## Pull requests

 ### Create (public PR on the upstream repo)

 ```bash
 gh pr create --web --repo <upstream> \
   --base <base-branch> --head <user>:<branch> \
   --title "<neutral title>" \
   --body "$(cat <path-to-body>)"
 ```

 `--web` is load-bearing. Per the per-project convention (for Airflow,
 see
 [`../../<project-config>/fix-workflow.md#pr-creation-convention`](../../<project-config>/fix-workflow.md#pr-creation-convention)),
 always open PRs through the browser so the human reviewer can check
 the title, body, and Gen-AI disclosure before clicking **Create**.

 ### Edit — backport / other labels

 ```bash
 gh pr edit <N> --repo <upstream> --add-label '<backport-label>'
 ```

 Safe to run immediately after PR creation; the backport bot acts on
 the label when the PR merges, not when it is applied.

 ### Cross-link from the public PR back to the private tracker

 **Forbidden.** The public PR body and any follow-up public comment must
 not reveal the CVE, the security nature, or the private tracker URL.
 Enforce via the scrub step before writing the PR body — see the
 per-project scrubbing rule (for Airflow,
 [`../../<project-config>/fix-workflow.md#pr-title--body-scrubbing`](../../<project-config>/fix-workflow.md#pr-title--body-scrubbing)).

 ## GraphQL (Projects V2)

 See [`project-board.md`](project-board.md) for the board
 introspection and `updateProjectV2ItemFieldValue` patterns.

 ## Error handling

 If any state-changing command fails, **stop the apply loop**, report
 the failure verbatim, and ask the user how to proceed — do not guess.
 Most sync-style skills order their apply list so the load-bearing edit
 (usually the body edit) is first; a failure on a later step leaves the
 body correct and a subsequent sync run will catch up the rest.
	<!-- START doctoc generated TOC please keep comment here to allow auto update -->
	<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
	Table of Contents generated with [DocToc](https://github.com/thlorenz/doctoc)

	- [GitHub — CLI and API operation catalogue](#github--cli-and-api-operation-catalogue)
	- [Authentication](#authentication)
	- [Collaborator lookup (security-team roster)](#collaborator-lookup-security-team-roster)
	- [Issues](#issues)
	- [Read](#read)
	- [Create](#create)
	- [Edit — labels](#edit--labels)
	- [Edit — assignees](#edit--assignees)
	- [Edit — body](#edit--body)
	- [Comment](#comment)
	- [Close / reopen](#close--reopen)
	- [Milestones](#milestones)
	- [List](#list)
	- [Create](#create-1)
	- [Assign to an issue](#assign-to-an-issue)
	- [Labels](#labels)
	- [List](#list-1)
	- [Create](#create-2)
	- [Pull requests](#pull-requests)
	- [Create (public PR on the upstream repo)](#create-public-pr-on-the-upstream-repo)
	- [Edit — backport / other labels](#edit--backport--other-labels)
	- [Cross-link from the public PR back to the private tracker](#cross-link-from-the-public-pr-back-to-the-private-tracker)
	- [GraphQL (Projects V2)](#graphql-projects-v2)
	- [Error handling](#error-handling)

	<!-- END doctoc generated TOC please keep comment here to allow auto update -->

	<!-- SPDX-License-Identifier: Apache-2.0
	https://www.apache.org/licenses/LICENSE-2.0 -->

	# GitHub — CLI and API operation catalogue

	Shared reference for the `gh` CLI and `gh api` / `gh api graphql`
	invocations the skills use against the project's tracker repository.
	The skills reference this file for the recipe shape; each inline
	command in a skill already substitutes the tracker repo slug from the
	adopting project's manifest (see
	[`../../<project-config>/project.md`](../../<project-config>/project.md#repositories)).

	Placeholder convention used below:

	- `<tracker>` — the tracker repository slug from
	`<project manifest>.tracker_repo` (for Airflow, `<tracker>`).
	- `<upstream>` — the upstream codebase slug from
	`<project manifest>.upstream_repo` (for Airflow, `<upstream>`).
	- `<N>` — issue or PR number.

	## Authentication

	Every skill's Step 0 pre-flight must verify that `gh` is authenticated
	and has collaborator access to `<tracker>`:

	```bash
	gh auth status # must show logged-in user + scopes
	gh api repos/<tracker> --jq .name # must return the repo name; 401/403/404 means stop
	```

	A non-zero exit on either command is a hard stop — the skill reports
	the failure and asks the user to `gh auth login` (or to ask for
	collaborator access to the tracker) rather than retrying.

	## Collaborator lookup (security-team roster)

	```bash
	gh api repos/<tracker>/collaborators --jq '.[].login'
	```

	The authoritative "who is on the security team" list. Every
	collaborator counts regardless of permission level (read / triage /
	write / maintain / admin). Roster snapshots maintained in the project
	manifest files (for Airflow, [`release-trains.md`](../../<project-config>/release-trains.md#security-team-roster))
	are caches of this command's output and can drift between changes.

	## Issues

	### Read

	```bash
	gh issue view <N> --repo <tracker> \
	--json number,title,state,body,labels,milestone,assignees,author
	```

	Add `--json comments` when the skill needs the comment trail, and
	`--json projectItems` when it needs to see which project boards the
	issue sits on.

	### Create

	```bash
	gh issue create --repo <tracker> \
	--title '<title>' \
	--body-file <path> \
	--label '<label-1>' --label '<label-2>'
	```

	Always write the body to a temp file and pass `--body-file` — shell
	quoting silently corrupts anything with literal backticks, `$(…)`, or
	newlines inside a multi-paragraph body.

	### Edit — labels

	```bash
	gh issue edit <N> --repo <tracker> \
	--add-label '<label-a>,<label-b>' \
	--remove-label '<label-c>'
	```

	Apply every add + remove in one call so the change lands as a
	single audit-trail entry rather than as N separate events.

	### Edit — assignees

	```bash
	gh issue edit <N> --repo <tracker> --add-assignee @me # self-assign
	gh issue edit <N> --repo <tracker> --add-assignee <handle> # named user
	```

	### Edit — body

	```bash
	gh issue edit <N> --repo <tracker> --body-file <tmpfile>
	```

	Write the edited body to a temp file first. The skills that perform
	"body-field surgery" (updating one `### <field>` section without
	touching the rest) read the full body, replace the targeted section
	between its header and the next `### ` heading, and write the result
	back via `--body-file`.

	### Comment

	```bash
	gh issue comment <N> --repo <tracker> --body-file <tmpfile>
	```

	Before posting, scrub the comment body for bare-name mentions of
	project maintainers / release managers / security-team members and
	replace with `@`-handles. See the per-project mention rule (for
	Airflow, [`../../<project-config>/naming-conventions.md#mentioning-airflow-maintainers-and-security-team-members`](../../<project-config>/naming-conventions.md#mentioning-airflow-maintainers-and-security-team-members))
	for the grep-list of names to check.

	### Close / reopen

	```bash
	gh issue close <N> --repo <tracker> --reason completed # or 'not planned'
	gh issue reopen <N> --repo <tracker>
	```

	## Milestones

	### List

	```bash
	gh api 'repos/<tracker>/milestones?state=all&per_page=100' \
	--jq '.[] \| select(.title == "<target>") \| {number, state}'
	```

	### Create

	```bash
	gh api repos/<tracker>/milestones \
	-f title='<target>' \
	-f state=open \
	-f description='<optional one-line description>'
	```

	The create call returns the milestone object including its `number` —
	capture that in case the milestone is later closed (see fallback
	below).

	### Assign to an issue

	```bash
	gh issue edit <N> --repo <tracker> --milestone '<title>'
	```

	Closed-milestone fallback. `gh issue edit --milestone '<title>'`
	fails with `'<title>' not found` if the milestone is closed. Fall back
	to the REST API and reference it by number:

	```bash
	gh api repos/<tracker>/issues/<N> -X PATCH -F milestone=<number>
	```

	## Labels

	### List

	```bash
	gh label list --repo <tracker> --limit 100 \
	--json name,description,color --jq '.[].name'
	```

	### Create

	```bash
	gh label create '<name>' --repo <tracker> \
	--description '<short description>' \
	--color '<hex>'
	```

	Do not silently create labels without asking the user. Label
	names are the shared vocabulary of the security team, and new labels
	should be discussed.

	## Pull requests

	### Create (public PR on the upstream repo)

	```bash
	gh pr create --web --repo <upstream> \
	--base <base-branch> --head <user>:<branch> \
	--title "<neutral title>" \
	--body "$(cat <path-to-body>)"
	```

	`--web` is load-bearing. Per the per-project convention (for Airflow,
	see
	[`../../<project-config>/fix-workflow.md#pr-creation-convention`](../../<project-config>/fix-workflow.md#pr-creation-convention)),
	always open PRs through the browser so the human reviewer can check
	the title, body, and Gen-AI disclosure before clicking Create.

	### Edit — backport / other labels

	```bash
	gh pr edit <N> --repo <upstream> --add-label '<backport-label>'
	```

	Safe to run immediately after PR creation; the backport bot acts on
	the label when the PR merges, not when it is applied.

	### Cross-link from the public PR back to the private tracker

	Forbidden. The public PR body and any follow-up public comment must
	not reveal the CVE, the security nature, or the private tracker URL.
	Enforce via the scrub step before writing the PR body — see the
	per-project scrubbing rule (for Airflow,
	[`../../<project-config>/fix-workflow.md#pr-title--body-scrubbing`](../../<project-config>/fix-workflow.md#pr-title--body-scrubbing)).

	## GraphQL (Projects V2)

	See [`project-board.md`](project-board.md) for the board
	introspection and `updateProjectV2ItemFieldValue` patterns.

	## Error handling

	If any state-changing command fails, stop the apply loop, report
	the failure verbatim, and ask the user how to proceed — do not guess.
	Most sync-style skills order their apply list so the load-bearing edit
	(usually the body edit) is first; a failure on a later step leaves the
	body correct and a subsequent sync run will catch up the rest.