Advanced

# Get details for the authenticated user.
# :path is relative to https://api.github.com/
gh api /user
# => {
# =>   "login": "alice",
# =>   "id": 12345678,
# =>   "name": "Alice Smith",
# =>   "email": "alice@example.com",
# =>   "public_repos": 42,
# =>   "followers": 120
# => }
 
# Get details for a specific repository using path placeholders.
# {owner} and {repo} are automatically resolved from the current git context.
gh api /repos/{owner}/{repo}
# => {
# =>   "name": "my-project",
# =>   "full_name": "alice/my-project",
# =>   "private": false,
# =>   "default_branch": "main",
# =>   "stargazers_count": 12
# => }
 
# Get rate limit status for the current token.
gh api /rate_limit
# => {
# =>   "resources": {
# =>     "core": {"limit": 5000, "remaining": 4876, "reset": 1680000000}
# =>   }
# => }

# POST: Create a repository topic using the REST API.
# --method specifies the HTTP verb; --field passes JSON body fields.
gh api \
  --method PUT \
  /repos/{owner}/{repo}/topics \
  --field names[]="typescript" \
  --field names[]="nextjs" \
  --field names[]="react"
# => (204 No Content — topics updated successfully)
 
# PATCH: Update a repository's description and homepage.
gh api \
  --method PATCH \
  /repos/{owner}/{repo} \
  --field description="My awesome TypeScript project" \
  --field homepage="https://myproject.example.com"
# => {
# =>   "name": "my-project",
# =>   "description": "My awesome TypeScript project",
# =>   "homepage": "https://myproject.example.com"
# => }
 
# POST: Create an issue via the API (alternative to gh issue create).
gh api \
  --method POST \
  /repos/{owner}/{repo}/issues \
  --field title="API-created issue" \
  --field body="Created via gh api" \
  --field labels[]="bug"
# => {
# =>   "number": 50,
# =>   "html_url": "https://github.com/alice/my-project/issues/50"
# => }

# Extract just the login names from a list of repository contributors.
gh api /repos/{owner}/{repo}/contributors --jq '.[].login'
# => alice
# => bob
# => carol
 
# Extract the number and title of open issues.
gh api /repos/{owner}/{repo}/issues --jq '.[] | "\(.number): \(.title)"'
# => 50: API-created issue
# => 43: Add dark mode support
# => 42: Fix login button alignment on mobile
 
# Extract a nested field: get the default branch name.
gh api /repos/{owner}/{repo} --jq '.default_branch'
# => main
 
# Filter and transform: get only issues with more than 5 comments.
gh api /repos/{owner}/{repo}/issues \
  --jq '.[] | select(.comments > 5) | {number: .number, title: .title, comments: .comments}'
# => {
# =>   "number": 30,
# =>   "title": "Document API endpoints",
# =>   "comments": 8
# => }

# Fetch all open issues across all pages (not just the first 30).
gh api /repos/{owner}/{repo}/issues --paginate
# => [
# =>   (all open issues, potentially hundreds, across all pages)
# => ]
 
# Paginate and extract just the issue numbers.
gh api /repos/{owner}/{repo}/issues \
  --paginate \
  --jq '.[].number'
# => 50
# => 43
# => 42
# => (all issue numbers, one per line)
 
# Paginate repository list for an organization (can be hundreds).
gh api /orgs/myorg/repos \
  --paginate \
  --jq '.[].full_name'
# => myorg/repo-1
# => myorg/repo-2
# => (all repository names in the organization)

# Query the authenticated user's profile and recent repositories.
gh api graphql --field query='
  query {
    viewer {
      login
      name
      repositories(first: 3, orderBy: {field: UPDATED_AT, direction: DESC}) {
        nodes {
          name
          stargazerCount
          primaryLanguage {
            name
          }
        }
      }
    }
  }
'
# => {
# =>   "data": {
# =>     "viewer": {
# =>       "login": "alice",
# =>       "name": "Alice Smith",
# =>       "repositories": {
# =>         "nodes": [
# =>           {"name": "my-project", "stargazerCount": 12, "primaryLanguage": {"name": "TypeScript"}},
# =>           {"name": "dotfiles", "stargazerCount": 3, "primaryLanguage": {"name": "Shell"}},
# =>           {"name": "cli-tools", "stargazerCount": 7, "primaryLanguage": {"name": "Go"}}
# =>         ]
# =>       }
# =>     }
# =>   }
# => }

# Parameterized query using GraphQL variables.
# Variables are passed separately from the query, preventing injection.
gh api graphql \
  --field query='
    query($owner: String!, $name: String!) {
      repository(owner: $owner, name: $name) {
        issues(first: 5, states: OPEN) {
          totalCount
          nodes {
            number
            title
            createdAt
          }
        }
      }
    }
  ' \
  --field owner="alice" \
  --field name="my-project"
# => {
# =>   "data": {
# =>     "repository": {
# =>       "issues": {
# =>         "totalCount": 5,
# =>         "nodes": [
# =>           {"number": 50, "title": "API-created issue", "createdAt": "2026-04-01T..."},
# =>           (4 more issues)
# =>         ]
# =>       }
# =>     }
# =>   }
# => }

# Install an extension by repository reference.
# Extensions are discovered at https://github.com/topics/gh-extension
gh extension install dlvhdr/gh-dash
# => ✓ Installed extension dlvhdr/gh-dash
# => (gh-dash adds: gh dash)
 
# Use the installed extension.
# Extensions run as gh subcommands using their repository name.
gh dash
# => (opens an interactive TUI dashboard for PRs and issues)
 
# Install another commonly used extension.
gh extension install seachicken/gh-poi
# => ✓ Installed extension seachicken/gh-poi
# => (gh-poi adds: gh poi — cleans merged local branches)
 
# List all installed extensions.
gh extension list
# => NAME     REPO                     VERSION
# => gh-dash  dlvhdr/gh-dash           v5.8.0
# => gh-poi   seachicken/gh-poi        v0.9.0
 
# Upgrade all extensions to their latest versions.
gh extension upgrade --all
# => ✓ Successfully upgraded extension dlvhdr/gh-dash
# => ✓ Successfully upgraded extension seachicken/gh-poi

# Create a new shell extension scaffold.
gh extension create my-extension
# => ✓ Created directory gh-my-extension
# => ✓ Initialized git repo
# => ✓ Made main script executable
# => ✓ Created gh-my-extension/gh-my-extension (the main script)
# => (current directory now contains gh-my-extension/)
 
# The scaffolded script is a basic bash script.
cat gh-my-extension/gh-my-extension
# => #!/usr/bin/env bash
# => set -e
# => echo "hello gh-my-extension!"
 
# Edit the script to add your functionality.
# Example: list all branches sorted by last commit date.
cat > gh-my-extension/gh-my-extension << 'EOF'
#!/usr/bin/env bash
set -e
# List remote branches sorted by last commit date
git for-each-ref --sort=-committerdate refs/remotes/origin \
  --format='%(committerdate:short) %(refname:short)' | head -20
EOF
 
# Install the extension from the local directory for testing.
gh extension install .
# => ✓ Installed extension gh-my-extension
 
# Run the extension.
gh my-extension
# => 2026-04-01  origin/main
# => 2026-03-30  origin/feat/dark-mode
# => (branches sorted by last commit date)

# Search for repositories about "rate limiting" in Go.
gh search repos "rate limiting" --language go --limit 5
# => NAME                            STARS  DESCRIPTION
# => toll-booth/throttle             1.2k   Distributed rate limiting in Go
# => ulule/limiter                   2.1k   Dead simple rate limit middleware for Go
# => mennanov/limiters               842    Redis-based rate limiters for Go
# => go-redis/redis_rate             3.4k   Rate limiting for go-redis
 
# Search repositories created by a specific organization with a topic.
gh search repos --owner github --topic "machine-learning" --limit 5
# => NAME                      STARS  DESCRIPTION
# => github/CodeSearchNet       4.2k   Benchmark dataset for code search
# => (more results)
 
# Search for repositories with many stars matching a term.
gh search repos "kubernetes operator" --language go --stars ">1000" --limit 5
# => NAME                          STARS  DESCRIPTION
# => operator-framework/operator-sdk  7.1k  SDK for building Kubernetes operators
# => (more results)

# Search for open issues mentioning a specific error message.
gh search issues "ECONNREFUSED connection refused" --state open --limit 5
# => REPO                    NUMBER  TITLE                                   UPDATED
# => nestjs/nest             #12345  ECONNREFUSED when starting dev server   2 days ago
# => expressjs/express       #3456   Connection refused on healthcheck        5 days ago
 
# Search for PRs that you authored across all repositories.
gh search prs --author @me --state open --limit 10
# => REPO                  NUMBER  TITLE                              UPDATED
# => alice/my-project      #45     Fix login button alignment          10 min ago
# => alice/other-project   #23     Update Node.js to v24              2 hours ago
 
# Search for issues assigned to you in a specific organization.
gh search issues --assignee @me --owner myorg --state open
# => (all open issues in myorg repositories assigned to you)
 
# Find PRs that need your review.
gh search prs "review-requested:@me" --state open
# => (open PRs where your review is requested, across all repositories)

# Search for code using a specific pattern in TypeScript files.
gh search code "useState" --language typescript --owner alice --limit 5
# => REPO                  FILE                          LINE
# => alice/my-project      src/components/Login.tsx      12: const [email, setEmail] = useState('')
# => alice/other-project   src/pages/index.tsx           8:  const [data, setData] = useState(null)
 
# Search for commits with a specific message pattern.
gh search commits "fix: login" --author alice --limit 5
# => SHA      REPO               COMMIT MESSAGE           DATE
# => abc1234  alice/my-project   fix: login button CSS    2026-04-01
# => def5678  alice/my-project   fix: login form submit   2026-03-28
 
# Search commits in a date range.
gh search commits "breaking change" \
  --committer-date ">2026-01-01" \
  --repo alice/my-project \
  --limit 10
# => (commits with "breaking change" in message since 2026-01-01)

# Get issue list as JSON with specific fields.
gh issue list --json number,title,labels,assignees
# => [
# =>   {
# =>     "number": 50,
# =>     "title": "API-created issue",
# =>     "labels": [{"name": "bug"}],
# =>     "assignees": [{"login": "alice"}]
# =>   },
# =>   (more issues)
# => ]
 
# Get PR list as JSON and filter with jq.
gh pr list --json number,title,headRefName,isDraft \
  --jq '.[] | select(.isDraft == false) | {number: .number, branch: .headRefName}'
# => {"number": 45, "branch": "fix/login-btn"}
# => (only non-draft PRs, showing number and branch)
 
# Get run list as JSON for scripting.
gh run list --json databaseId,name,status,conclusion --limit 10
# => [
# =>   {"databaseId": 123456789, "name": "CI", "status": "completed", "conclusion": "success"},
# =>   (more runs)
# => ]

#!/usr/bin/env bash
# Automate the full feature branch lifecycle:
# create branch → commit → push → create PR → wait for CI → merge
 
set -euo pipefail
# => set -e: exit on error; set -u: error on unset variable; set -o pipefail: fail on pipe error
 
FEATURE_NAME="${1:?Usage: $0 <feature-name>}"
# => Requires first argument; shows usage if missing
 
# Create and checkout feature branch.
git checkout -b "feat/$FEATURE_NAME"
# => Creates and switches to the new feature branch
 
# (make your code changes here, then stage them)
git add -A
git commit -m "feat: $FEATURE_NAME"
# => Commits staged changes with conventional commit message
 
# Push the branch and create a PR as draft.
git push -u origin "feat/$FEATURE_NAME"
# => Pushes branch to origin and sets upstream tracking
 
gh pr create \
  --title "feat: $FEATURE_NAME" \
  --body "Automated PR for $FEATURE_NAME" \
  --draft
# => Creates draft PR — reviewers not yet notified
 
# Wait for CI to complete, then mark ready for review.
gh pr checks --watch
# => Blocks until all CI checks complete (exits non-zero on failure)
 
gh pr ready
# => Marks PR as ready — notifies reviewers
echo "PR ready for review: $(gh pr view --json url --jq '.url')"
# => Prints the PR URL for sharing in Slack or email

#!/usr/bin/env bash
# Add a label to all repositories in an organization that don't have it yet.
 
ORG="${1:?Usage: $0 <org-name>}"
# => Requires organization name argument
 
LABEL_NAME="needs-review"
LABEL_COLOR="0173B2"
# => Define the label to create
 
# Get all repo names as a newline-separated list.
gh repo list "$ORG" \
  --limit 1000 \
  --json nameWithOwner \
  --jq '.[].nameWithOwner' | while read -r REPO; do
  # => Each REPO value is like "myorg/repo-name"
 
  echo "Processing $REPO..."
  # => Log progress for each repository
 
  # Create label, ignoring error if it already exists.
  gh label create "$LABEL_NAME" \
    --color "$LABEL_COLOR" \
    --repo "$REPO" \
    --description "Requires maintainer review" 2>/dev/null || true
  # => 2>/dev/null suppresses "already exists" error
  # => || true prevents the loop from exiting on the suppressed error
done
 
echo "Done. Label '$LABEL_NAME' synchronized across $ORG."

# In a GitHub Actions workflow step, gh is already authenticated.
# No login step is needed — GITHUB_TOKEN is set automatically by GitHub.
# The workflow YAML step would look like:
#
# - name: Comment PR with deployment URL
#   env:
#     GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
#   run: |
#     gh pr comment "${{ github.event.pull_request.number }}" \
#       --body "Deployed to staging: https://staging-${{ github.sha }}.example.com"
 
# Simulate this pattern in a local test (export GH_TOKEN manually):
export GH_TOKEN="$(gh auth token)"
# => Exports the current authentication token for sub-processes
 
PR_NUMBER=45
DEPLOY_URL="https://staging-abc1234.example.com"
 
gh pr comment "$PR_NUMBER" \
  --body "Deployment successful. Preview: $DEPLOY_URL"
# => https://github.com/alice/my-project/pull/45#issuecomment-123456793
# => Comment posted on the PR with the deployment URL
 
# Auto-merge a PR after all CI checks pass (used in workflow triggers).
gh pr merge "$PR_NUMBER" --auto --squash --delete-branch
# => ✓ Pull request #45 will be automatically merged via squash when all requirements are met.

# List all GitHub Actions caches for the current repository.
gh cache list
# => ID          KEY                                 SIZE    CREATED           ACCESSED
# => 123456789   node-modules-abc1234-package-lock   245 MB  about 2 hours ago  about 2 hours ago
# => 123456788   node-modules-def5678-package-lock   240 MB  about 1 day ago    about 1 day ago
# => 123456787   go-modules-xyz789-go.sum            82 MB   about 3 days ago   about 3 days ago
 
# Delete a specific cache by ID.
gh cache delete 123456788
# => ✓ Deleted cache 123456788
 
# Delete all caches for the current repository (useful after a lock file change).
gh cache delete --all
# => ✓ Deleted all 3 caches from alice/my-project
 
# Delete caches for a specific branch (after a branch is deleted).
gh cache list --branch feat/dark-mode
# => (lists caches scoped to the feat/dark-mode branch)
gh cache delete --all --branch feat/dark-mode
# => ✓ Deleted all caches for branch feat/dark-mode

# Download the release binary to verify.
gh release download v1.2.0 --pattern "my-app-linux-amd64"
# => my-app-linux-amd64  downloaded  8.4 MB
 
# Verify the attestation for the downloaded binary.
# --owner specifies whose attestations to check.
gh attestation verify my-app-linux-amd64 --owner alice
# => Loaded digest sha256:abc123... for file://my-app-linux-amd64
# => ✓ Verifying attestations for artifact
# =>
# => The following 1 attestation(s) were verified:
# =>
# => - Attestation from: https://github.com/alice/my-project/actions/runs/123456789
# =>   - Build started at: 2026-04-01T10:00:00Z
# =>   - Signer Workflow: .github/workflows/release.yml
# =>   - SLSA Level: Build L3

# Export your public GPG key and add it to GitHub.
# The key ID can be found with: gpg --list-secret-keys --keyid-format LONG
gpg --armor --export ABC123DEF456 | gh gpg-key add --title "Work Laptop 2026"
# => ✓ GPG key added to your account
 
# List all GPG keys registered on your account.
gh gpg-key list
# => ID       KEY ID (16-char)  TITLE             EMAILS          EXPIRES   ADDED
# => 9876543  ABC123DEF456789A  Work Laptop 2026  alice@ex.com    Never     about 5 min ago
# => 1234567  XYZ789GHI012JKL0  Old Key           alice@ex.com    2025-01-01  2 years ago
 
# Delete an expired GPG key.
gh gpg-key delete 1234567
# => ✓ GPG key 1234567 deleted from your account

# List all projects for the current authenticated user.
gh project list
# => NUMBER  TITLE           STATE  ID
# => 1       Sprint Board    open   PVT_kwABC123
# => 2       Backlog         open   PVT_kwDEF456
# => 3       2025 Q4 Goals   closed PVT_kwGHI789
 
# List projects for an organization.
gh project list --owner myorg
# => NUMBER  TITLE                STATE  ID
# => 1       Engineering Roadmap  open   PVT_kwORG123
# => 2       Security Audit 2026  open   PVT_kwORG456
 
# View details of a specific project.
gh project view 1 --owner alice
# => Title: Sprint Board
# => Number: 1
# => State: open
# => (item count and field definitions displayed)

# Create a new project for the current user.
gh project create --owner alice --title "Q2 2026 Roadmap"
# => https://github.com/users/alice/projects/4
# => (project created with ID 4)
 
# Add an issue to the project by its URL.
gh project item-add 4 \
  --owner alice \
  --url https://github.com/alice/my-project/issues/42
# => https://github.com/users/alice/projects/4
# => (issue #42 added as an item to project 4)
 
# Add a PR to the project.
gh project item-add 4 \
  --owner alice \
  --url https://github.com/alice/my-project/pull/45
# => (PR #45 added as an item to project 4)
 
# List all items in a project.
gh project item-list 4 --owner alice --limit 20
# => TYPE   TITLE                                  NUMBER  REPO
# => ISSUE  Fix login button alignment on mobile   #42     alice/my-project
# => PR     Fix login button alignment on mobile   #45     alice/my-project

# List all fields defined on project number 4.
gh project field-list 4 --owner alice
# => NAME        DATATYPE  ID
# => Status      SINGLE_SELECT  PVTF_kwABC123
# => Priority    SINGLE_SELECT  PVTF_kwDEF456
# => Sprint      ITERATION      PVTF_kwGHI789
# => Estimate    NUMBER         PVTF_kwJKL012
 
# The field IDs are used with gh project item-edit to update values.
# Update an item's Status to "In Progress" via the GraphQL API.
gh api graphql --field query='
  mutation($projectId: ID!, $itemId: ID!, $fieldId: ID!, $value: String!) {
    updateProjectV2ItemFieldValue(input: {
      projectId: $projectId
      itemId: $itemId
      fieldId: $fieldId
      value: {singleSelectOptionId: $value}
    }) {
      projectV2Item { id }
    }
  }
' \
  --field projectId="PVT_kwABC123" \
  --field itemId="PVTI_kwABC123" \
  --field fieldId="PVTF_kwABC123" \
  --field value="in-progress-option-id"
# => {"data": {"updateProjectV2ItemFieldValue": {"projectV2Item": {"id": "PVTI_kwABC123"}}}}

# Define a comprehensive PR workflow alias.
# This alias: pushes the branch, creates a draft PR, then marks it ready after CI.
gh alias set submit '!
  set -e
  BRANCH="$(git symbolic-ref --short HEAD)"
  git push -u origin "$BRANCH"
  gh pr create \
    --title "$(git log -1 --pretty=%s)" \
    --body "$(git log -1 --pretty=%b)" \
    --draft
  echo "PR created as draft. Waiting for CI..."
  gh pr checks --watch
  gh pr ready
  echo "PR ready: $(gh pr view --json url --jq .url)"
'
# => ✓ Added alias for submit
 
# Use the alias to submit the current branch.
gh submit
# => (pushes branch, creates draft PR with last commit message, waits for CI, marks ready)

#!/usr/bin/env bash
# Full release automation: validate CI, create tag, publish release.
 
set -euo pipefail
 
VERSION="${1:?Usage: $0 <version>}"
# => e.g., v1.3.0
 
# Confirm main branch CI is green before releasing.
LATEST_RUN_CONCLUSION=$(
  gh run list \
    --branch main \
    --workflow CI \
    --limit 1 \
    --json conclusion \
    --jq '.[0].conclusion'
)
# => Gets the conclusion of the most recent CI run on main
 
if [[ "$LATEST_RUN_CONCLUSION" != "success" ]]; then
  echo "ERROR: Latest CI run on main is '$LATEST_RUN_CONCLUSION'. Aborting release."
  exit 1
fi
# => Abort if CI is not passing — never release from a red main
 
# Create and push the version tag.
git tag -s "$VERSION" -m "Release $VERSION"
# => Creates a signed git tag (requires GPG setup)
 
git push origin "$VERSION"
# => Pushes the tag to GitHub, which may trigger a release workflow
 
# Create the GitHub Release with auto-generated notes.
gh release create "$VERSION" \
  --title "$VERSION" \
  --generate-notes \
  --verify-tag
# => ✓ Created release v1.3.0
# => (--verify-tag ensures the tag exists before creating the release)
 
echo "Released $VERSION: $(gh release view "$VERSION" --json url --jq .url)"
# => Released v1.3.0: https://github.com/alice/my-project/releases/tag/v1.3.0

#!/usr/bin/env bash
# Add a "stale" label to issues with no activity in 90 days.
 
STALE_DAYS=90
STALE_DATE=$(date -v-"${STALE_DAYS}"d +%Y-%m-%d 2>/dev/null || date -d "-${STALE_DAYS} days" +%Y-%m-%d)
# => Compute the cutoff date (works on macOS and Linux)
 
# Get all open issues updated before the cutoff date.
gh issue list \
  --state open \
  --limit 1000 \
  --json number,title,updatedAt \
  --jq --arg date "$STALE_DATE" \
  '.[] | select(.updatedAt < $date) | .number' | while read -r ISSUE_NUMBER; do
  # => Each iteration processes one stale issue number
 
  echo "Marking issue #$ISSUE_NUMBER as stale..."
  # => Log progress
 
  gh issue edit "$ISSUE_NUMBER" --add-label "stale"
  # => Adds the stale label to the issue
 
  gh issue comment "$ISSUE_NUMBER" \
    --body "This issue has had no activity for ${STALE_DAYS} days and has been marked stale. It will be closed in 14 days if there is no further activity."
  # => Posts a stale notification comment
done
 
echo "Stale issue sweep complete."

#!/usr/bin/env bash
# Deploy a specific version to production by triggering a deployment
# workflow in a separate infrastructure repository.
 
APP_VERSION="${1:?Usage: $0 <version>}"
# => e.g., v1.3.0
 
INFRA_REPO="myorg/infrastructure"
# => The repository containing the deployment workflows
 
# Trigger the deployment workflow with the version as input.
gh workflow run "deploy-production.yml" \
  --repo "$INFRA_REPO" \
  --field app_version="$APP_VERSION" \
  --field notify_slack="true"
# => ✓ Created workflow_dispatch event for deploy-production.yml at main
 
# Wait a moment for the run to be queued before watching it.
sleep 3
# => Give GitHub time to register the new run
 
# Watch the deployment run to completion.
DEPLOY_RUN_ID=$(
  gh run list \
    --repo "$INFRA_REPO" \
    --workflow "deploy-production.yml" \
    --limit 1 \
    --json databaseId \
    --jq '.[0].databaseId'
)
# => Gets the ID of the run just triggered
 
gh run watch "$DEPLOY_RUN_ID" --repo "$INFRA_REPO"
# => Streams the deployment workflow progress until completion
# => Exit code 0 = deployment succeeded; non-zero = deployment failed
 
echo "Deployment of $APP_VERSION complete."

# REST call: get repository star count.
gh api /repos/cli/cli --jq '.stargazers_count'
# => 38421
# => (single JSON number extracted directly from the REST response)
 
# GraphQL call: get the same data with a typed query.
gh api graphql \
  --field query='query { repository(owner: "cli", name: "cli") { stargazerCount } }' \
  --jq '.data.repository.stargazerCount'
# => 38421
# => (same result via GraphQL — useful when you need multiple fields in one request)

# Complete PR lifecycle from current branch — all in the terminal.
 
# 1. Create draft PR (start CI without notifying reviewers).
gh pr create --title "$(git log -1 --pretty=%s)" --draft
# => PR created as draft
 
# 2. Watch CI until completion.
gh pr checks --watch
# => All checks pass (exit code 0)
 
# 3. Mark ready — notifies reviewers.
gh pr ready
# => PR marked as ready for review
 
# 4. After approval (checked with gh pr view), merge with squash.
gh pr merge --squash --delete-branch --auto
# => PR will auto-merge when all requirements are met

#!/usr/bin/env bash
# .git/hooks/pre-push
# Prevent pushing to main if any security advisory is open for the repository.
 
set -euo pipefail
 
# Only run this check when pushing to the remote named "origin".
REMOTE="$1"
# => First argument to pre-push hook is the remote name
 
if [[ "$REMOTE" != "origin" ]]; then
  exit 0
  # => Skip the check for non-origin remotes (e.g., local forks)
fi
 
# Query for open security advisories on this repository.
ADVISORY_COUNT=$(
  gh api /repos/{owner}/{repo}/security-advisories \
    --jq '[.[] | select(.state == "published")] | length'
)
# => Counts published (unresolved) security advisories
 
if [[ "$ADVISORY_COUNT" -gt 0 ]]; then
  echo "ERROR: $ADVISORY_COUNT open security advisory(ies) found."
  echo "Resolve them before pushing: $(gh repo view --json url --jq .url)/security/advisories"
  exit 1
  # => Block the push and print the advisory URL for action
fi
 
echo "Security check passed. No open advisories."
exit 0
# => Allow the push to proceed

#!/usr/bin/env bash
# Developer onboarding: authenticate, clone all org repos, configure labels.
# Usage: ./onboard.sh <github-org> <team-name>
 
set -euo pipefail
 
ORG="${1:?Usage: $0 <org> <team>}"
TEAM="${2:?Usage: $0 <org> <team>}"
WORKSPACE_DIR="$HOME/code/$ORG"
# => Organize all org repos under ~/code/<org>/
 
echo "=== GitHub CLI Onboarding for $ORG/$TEAM ==="
 
# Step 1: Verify authentication.
if ! gh auth status --hostname github.com &>/dev/null; then
  echo "Not authenticated. Starting login flow..."
  gh auth login --hostname github.com --git-protocol ssh
fi
# => Checks auth silently; triggers login if not authenticated
 
USERNAME=$(gh api /user --jq .login)
echo "Authenticated as: $USERNAME"
# => Confirms who we are authenticated as
 
# Step 2: Create workspace directory.
mkdir -p "$WORKSPACE_DIR"
echo "Workspace: $WORKSPACE_DIR"
# => Creates the workspace directory if it does not exist
 
# Step 3: Clone all repos where the team has push access.
echo "Cloning team repositories..."
gh api "/orgs/$ORG/teams/$TEAM/repos" \
  --paginate \
  --jq '.[] | select(.permissions.push == true) | .full_name' | while read -r REPO; do
  # => Paginate through all repos the team has push access to
 
  REPO_DIR="$WORKSPACE_DIR/$(basename "$REPO")"
  if [[ -d "$REPO_DIR" ]]; then
    echo "  Skipping $REPO (already cloned)"
    continue
    # => Skip already-cloned repos (idempotent)
  fi
 
  echo "  Cloning $REPO..."
  gh repo clone "$REPO" "$REPO_DIR"
  # => Clone using gh (uses configured protocol, handles auth)
done
 
# Step 4: Configure global gh settings.
gh config set editor "code --wait"
gh config set git_protocol ssh
# => Set preferred editor and protocol for the new developer
 
# Step 5: Install standard team extensions.
gh extension install dlvhdr/gh-dash 2>/dev/null || true
# => Install the dashboard extension (ignore if already installed)
 
echo "=== Onboarding complete for $USERNAME ==="
echo "Repos cloned to: $WORKSPACE_DIR"
echo "Run 'gh dash' to open the PR dashboard."