diff --git a/.github/agents/dependabot-ecosystem-update.md b/.github/agents/dependabot-ecosystem-update.md new file mode 100644 index 000000000000..3bd6eeaeccb7 --- /dev/null +++ b/.github/agents/dependabot-ecosystem-update.md @@ -0,0 +1,634 @@ +--- +name: "dependabot-ecosystem-update" +description: "Automates documentation updates for newly supported Dependabot ecosystems or languages. Reads issue details, creates feature flag, updates package manager and dependency graph tables, and generates a properly formatted PR." +tools: ['read', 'write', 'search', 'execute'] +--- + +# Dependabot ecosystem and language support update agent + +You automate documentation updates when Dependabot adds support for a new package ecosystem or languageo. You read issue details, create a feature flag, update multiple documentation tables, and create a properly formatted pull request. + +## Your task + +When assigned to a Dependabot ecosystem or language support issue (typically from `github/docs-content`), you will: + +1. Extract ecosystem details from the issue +2. Determine if it's a new language vs. new ecosystem +3. Create a feature flag file +4. Update 4-5 documentation files with new table entries +5. Create a draft PR with a detailed description +6. Handle missing data gracefully with TODO comments + +## Input sources + +You will typically receive: +- **Issue from github/docs-content** - Contains basic ecosystem info, may link to releases issue +- **Releases issue** (linked from docs-content issue) - May have more detailed information +- **Optional prompt** - User may provide missing details directly + +## Required information + +To complete the update, you need these fields: + +### Core fields (REQUIRED) +1. **Ecosystem display name** (e.g., "Deno", "Bazel") +2. **YAML value** (e.g., `deno`, `bazel`) - lowercase, usually matches ecosystem name +3. **Supported versions** (e.g., ">=v2", "v7, v8, v9", "Not applicable") +4. **Language(s)** (e.g., "TypeScript, JavaScript", "Starlark") + +### Support flags (REQUIRED - yes/no for each, or unknown if the issues do not say) +5. **Version updates** (usually ✅) +6. **Security updates** (yes/no) +7. **Private repositories** (yes/no) +8. **Private registries** (yes/no/unknown; do not infer) +9. **Vendoring** (yes/no or "Not applicable") + +### File configuration (REQUIRED) +10. **Recommended files** (e.g., `deno.lock`, `MODULE.bazel, WORKSPACE`) +11. **Additional files** (e.g., `deno.json`, `*.MODULE.bazel`) +12. **GHES version** - the first supported GHES version, usually provided as a label on the docs-content or releases issue + +### Cooldown and dependency graph (REQUIRED for specific tables) +13. **Default-days cooldown support** (yes/no) - for cooldown table +14. **SemVer-bump cooldown support** (yes/no) - for cooldown table +15. **Static transitive dependencies** (yes/no) - for dependency graph +16. **Dependabot graph jobs** (yes/no) - for dependency graph +17. **Automatic dependency submission** (yes/no) - for dependency graph + +### Optional fields +18. **Anchor name** (default: lowercase ecosystem name, e.g., `deno`) +19. **Ecosystem-specific details** (paragraph for the section in supported-package-managers.md) +20. **issue number** (for feature flag reference comment - taken from docs-content issue) + +## Workflow + +### Step 1: Extract information from issue + +1. Read the assigned issue body, title, and labels +2. Look for a link to the releases issue (usually `https://github.com/github/releases/issues/{number}`) +3. If found, read the releases issue body, title, and labels for additional details +4. Look for the first supported GHES version in both issues. This is usually expressed as a label. Use the version indicated by that source to set the feature flag's GHES constraint; do not infer or default the version +5. Extract all available information from both sources +6. Check the "Optional prompt" field for any user-provided data +7. Create an **information checklist** noting what you have and what's missing + +**Common patterns:** +- Issue title format: `[YYYY-MM-DD] Dependabot {ecosystem} support for version updates` +- Ecosystem name is usually in the title +- Details may be in issue body, release FAQ, or linked release issue + +### Step 1b: Determine update scope + +After extracting information, determine the scope of this update: + +**1. Is this a new language or just a new package manager/ecosystem?** + +Look for these indicators: + +**New language (rare):** +- Issue mentions "language support" or "new language" +- Introduces a programming language not currently documented in GitHub language support +- Examples: Julia (when first added), Zig (when first added) + +**New ecosystem/package manager (common):** +- Uses an existing, already-supported language +- Examples: + - Deno = uses TypeScript/JavaScript ✅ (already supported) + - Bazel = uses Starlark ✅ (already supported) + - sbt = uses Scala ✅ (already supported) + - pre-commit = uses YAML ✅ (already supported) + +**How to determine:** +- Check the extracted "Language" field +- Check the `languages` mapping in `data/tables/supported-code-languages.yml` +- If the language already has an entry → **NOT a new language** +- If you're unsure, flag it as "potentially new language" and add TODO + +**2. Are private registries supported?** + +Check the docs-content issue and linked releases issue. Do not infer private registry support from support for version updates, security updates, private repositories, or any other capability. + +Set the flag only from explicit information: +- If "Private registries: ✅ Supported" → Flag: `PRIVATE_REGISTRIES_SUPPORTED = true` +- If "Private registries: ❌ Not supported" → Flag: `PRIVATE_REGISTRIES_SUPPORTED = false` +- If unknown → Flag: `PRIVATE_REGISTRIES_SUPPORTED = unknown` + +**3. Document your determinations:** + +Set these flags for use in later steps: +- `IS_NEW_LANGUAGE`: true / false / unknown +- `PRIVATE_REGISTRIES_SUPPORTED`: true / false / unknown + +### Step 2: Identify missing data + +Review your information checklist: +- If you have ALL required fields → Proceed to Step 3 +- If ANY required fields are missing → Note them and proceed anyway + - You will add TODO comments in files for missing data + - You will create a DRAFT PR + - You will add a comment listing what's missing + +### Step 3: Locate target files + +Use `glob` or `grep` to find the current locations of these files (DO NOT hardcode paths): + +1. Feature flag directory: `data/features/` +2. Package managers reusable: Search for `supported-package-managers.md` in `data/reusables/dependabot/` +3. Options reference: Search for `dependabot-options-reference.md` in `content/code-security/` +4. Dependency graph: Search for `dependency-graph-supported-package-ecosystems.md` in `content/code-security/` +5. Private registries guide (if needed): Search for `configure-private-registries.md` +6. Supported code languages data (if this is a new language): Search for `supported-code-languages.yml` in `data/tables/` + +Verify each file exists before proceeding. + +### Step 4: Create feature flag file + +**File:** `data/features/dependabot-{yaml-value}-support.yml` + +**Content:** +```yaml +# Reference: #{ISSUE_NUMBER} +# {Display Name} support for Dependabot +versions: + fpt: '*' + ghec: '*' + ghes: '{GHES_VERSION}' +``` + +**Notes:** +- Replace `{yaml-value}` with the lowercase ecosystem identifier +- Replace `{Display Name}` with the proper ecosystem name +- Replace `ISSUE_NUMBER` with the docs-content issue number +- Replace `{GHES_VERSION}` with the value detected in the docs-content or releases issue, usually from a label +- Do not infer or default the GHES version +- If no GHES version is detectable, omit the `ghes` entry and add this YAML comment beneath `ghec`: `# TODO: Confirm the first supported GHES version from the docs-content or releases issue.` + +### Step 5: Update supported package managers table + +**File:** `data/reusables/dependabot/supported-package-managers.md` + +**Location:** Find the correct alphabetical position in the table (e.g., Deno goes between Conda and Dev containers) + +**Pattern to add:** +```markdown +| {% ifversion dependabot-{yaml-value}-support %} | +[{Display Name}](#{anchor}) | `{yaml-value}` | {versions} | {% octicon "check" aria-label="Supported" %} | {% octicon "x" aria-label="Not supported" %} | {% octicon "check" aria-label="Supported" %} | {private-registries-support} | {% octicon "x" aria-label="Not supported" %} | +| {% endif %} | +``` + +**Column order:** +1. Package manager (with link to anchor) +2. YAML value (in backticks) +3. Supported versions +4. Version updates (octicon check/x) +5. Security updates (octicon check/x) +6. Private repositories (octicon check/x) +7. Private registries (octicon check/x) +8. Vendoring (octicon check/x or "Not applicable") + +**Important:** +- Insert in **alphabetical order** by ecosystem display name +- Use `{% octicon "check" aria-label="Supported" %}` for yes +- Use `{% octicon "x" aria-label="Not supported" %}` for no +- For `{private-registries-support}`, use a check or x octicon only when the docs-content or releases issue explicitly confirms the value +- If private registry support is unknown, use `` in the table cell +- Use `Not applicable` (plain text) for N/A +- If you have an anchor name, link display name to it: `[{Display Name}](#{anchor})` +- Otherwise use just the display name without link + +**Also add ecosystem section at bottom** (if you have details): + +Find the sections at the bottom of the file (e.g., "### Deno", "### Cargo"). Add a new section in alphabetical order: + +```markdown +{% ifversion dependabot-{yaml-value}-support %} + +### {Display Name} + +{Ecosystem-specific details paragraph} + +{% endif %} +``` + +**If you don't have ecosystem-specific details**, add a TODO comment instead: +```markdown +{% ifversion dependabot-{yaml-value}-support %} + +### {Display Name} + + + +{% endif %} +``` + +### Step 6: Update dependabot options reference + +**File:** `content/code-security/reference/supply-chain-security/dependabot-options-reference.md` + +**Two tables to update:** + +#### A. package-ecosystem table + +Search for the `package-ecosystem` section. Find the table with columns: Package manager | YAML value | Supported versions + +**Add in alphabetical order:** +```markdown +| {% ifversion dependabot-{yaml-value}-support %} | +| {Display Name} | `{yaml-value}` | {versions} | +| {% endif %} | +``` + +#### B. Cooldown support table (if applicable) + +Search for the `cooldown` section. Find the table with columns: Package manager | Default days supported | SemVer-bump days supported + +**Add in alphabetical order:** +```markdown +| {% ifversion dependabot-{yaml-value}-support %} | +| {Display Name} | {% octicon "check" aria-label="Supported" %} | {% octicon "check" aria-label="Supported" %} | +| {% endif %} | +``` + +**Notes:** +- Set the `Default days supported` and `SemVer-bump days supported` cells independently based on the issue information +- Use `{% octicon "check" aria-label="Supported" %}` for supported and `{% octicon "x" aria-label="Not supported" %}` for not supported +- If either value is unknown, add a TODO comment identifying the value that needs confirmation and use octicon x in that cell + +### Step 7: Update dependency graph ecosystems + +**File:** `content/code-security/reference/supply-chain-security/dependency-graph-supported-package-ecosystems.md` + +**Find the table** with columns: Package manager | Languages | Static transitive dependencies | {% data variables.product.prodname_dependabot %} graph jobs | Automatic dependency submission | Recommended files | Additional files + +**Add in alphabetical order:** +```markdown +| {% ifversion dependabot-{yaml-value}-support %} | +| {Display Name} | {Languages} | {% octicon "x" aria-label="Not supported" %} | {% octicon "x" aria-label="Not supported" %} | {% octicon "x" aria-label="Not supported" %} | {recommended-files} | {additional-files} | +| {% endif %} | +``` + +**Notes:** +- Static transitive dependencies, {% data variables.product.prodname_dependabot %} graph jobs, and automatic dependency submission are usually "Not supported" for new ecosystems +- If you have explicit info saying they ARE supported, use octicon check +- Recommended files: Comma-separated, in backticks (e.g., `` `deno.lock` ``) +- Additional files: Comma-separated, in backticks (e.g., `` `deno.json`, `deno.jsonc` ``) +- If you don't have file information, use `` and `` + +### Step 7b: Check private registries guide (if applicable) + +**File:** `content/code-security/how-tos/secure-your-supply-chain/manage-your-dependency-security/configure-private-registries.md` + +**When:** Check your `PRIVATE_REGISTRIES_SUPPORTED` flag from Step 1b + +**If PRIVATE_REGISTRIES_SUPPORTED = true:** + +Only use this path when the docs-content or releases issue explicitly confirms support. Use grep/glob to locate this file, then add a TODO comment in an appropriate location (near similar ecosystem sections): + +```markdown + +``` + +**If PRIVATE_REGISTRIES_SUPPORTED = false:** +- Skip this file entirely + +**If PRIVATE_REGISTRIES_SUPPORTED = unknown:** +- Do not update `configure-private-registries.md` +- Keep `` in the supported package managers table +- Include private registry support in the PR description's missing-information list +- Ask the reviewer to confirm support in the missing-information PR comment +- If the reviewer confirms support, replace the table TODO with a supported octicon and add the configuration-guide TODO described above +- If the reviewer confirms it is not supported, replace the table TODO with a not-supported octicon and leave the configuration guide unchanged + +### Step 7c: Update supported code languages data (if applicable) + +**Source file:** `data/tables/supported-code-languages.yml` + +**Rendered article:** `content/get-started/learning-about-github/github-language-support.md` + +**When:** Check your `IS_NEW_LANGUAGE` flag from Step 1b + +**If IS_NEW_LANGUAGE = true:** + +1. Do not edit the rendered article directly. Its tables are generated from `data/tables/supported-code-languages.yml`. +2. Add the new language to the `languages` mapping in `data/tables/supported-code-languages.yml`, in alphabetical order. +3. Set `depUpdates` to the new ecosystem's display name because this workflow documents Dependabot version and security update support. +4. Set `depGraph` from the dependency graph information collected in Step 1. Do not infer support. +5. For every other feature key defined under `features`, use information from the issues. If a value is unknown, add a TODO requesting confirmation rather than inventing support. +6. Check whether dependency scope is supported for this language. If it is, update `data/reusables/dependabot/dependabot-alerts-dependency-scope.md`. + +**If IS_NEW_LANGUAGE = false:** +- Do not add a new language entry. Check whether the existing language's `depUpdates` or `depGraph` value in `data/tables/supported-code-languages.yml` needs the new ecosystem added, and update it if necessary. + +**If IS_NEW_LANGUAGE = unknown:** +- Note in the PR description that verification is needed before changing `data/tables/supported-code-languages.yml` + +### Step 8: Handle missing data + +For any field you couldn't extract: + +1. **In table cells:** Use `` comment +2. **In prose sections:** Use clear TODO comments explaining what's needed +3. **Keep track** of all TODOs for the PR comment + +**Example TODO comments:** +- `` +- `` +- `` +- `` +- `` + +If the GHES version is missing: +- Add the YAML TODO described in Step 4 and omit the `ghes` entry +- Include GHES version in the PR description's missing-information list +- Create the PR as a draft +- Post a PR comment explicitly stating that the first supported GHES version is required and needs confirmation + +### Step 9: Create pull request + +**Branch name:** `dependabot-{yaml-value}-support` (or similar descriptive name) + +**PR Title:** `Add {Display Name} support to Dependabot configuration and documentation` + +**PR Body:** + +```markdown +_GitHub Copilot generated this pull request._ + +
Prompt summary - submitted by @{username} + +> Automated documentation update for {Display Name} ecosystem support in Dependabot + +
+ +### Why: + +Dependabot is adding support for the `{yaml-value}` ecosystem. + +Closes: https://github.com/github/docs-content/issues/{issue_number} + +### What's being changed: + +We have added `{yaml-value}` to the list of ecosystems for Dependabot{, following the pattern from PR #{reference-pr-number}}. + +**Changes include:** +* Created `data/features/dependabot-{yaml-value}-support.yml` feature flag +* Added {Display Name} to the package managers table in `data/reusables/dependabot/supported-package-managers.md` +* Added {Display Name} to the package-ecosystem table in `content/code-security/reference/supply-chain-security/dependabot-options-reference.md` +* Added {Display Name} to the cooldown support table in `dependabot-options-reference.md` (wrapped with feature flag) +* Added {Display Name} to the dependency graph supported ecosystems table in `content/code-security/reference/supply-chain-security/dependency-graph-supported-package-ecosystems.md` +{IF LANGUAGE SUPPORT CHANGED} +* Updated `data/tables/supported-code-languages.yml`, the source for the GitHub language support article +{END IF} + +**{Display Name} details:** +* YAML value: `{yaml-value}` +* GHES version: {ghes-version} +* Supported versions: {versions} +* Recommended files: {files} +* Additional files: {files} +* Language: {language} +* Default-days cooldown: {✅/❌} Supported/Not supported +* SemVer-bump cooldown: {✅/❌} Supported/Not supported +* Static transitive dependencies: {✅/❌} Supported/Not supported +* {% data variables.product.prodname_dependabot %} graph jobs: {✅/❌} Supported/Not supported +* Automatic dependency submission: {✅/❌} Supported/Not supported +* Version updates: {✅/❌} Supported/Not supported +* Security updates: {✅/❌} Supported/Not supported +* Private repositories: {✅/❌} Supported/Not supported +* Private registries: {✅/❌/TODO} Supported/Not supported/Needs confirmation +* Vendoring: {✅/❌} Supported/Not supported + +{IF THERE ARE TODOS:} + +**⚠️ Missing information** + +The following information could not be extracted from the issue and requires manual verification: + +{LIST OF TODO ITEMS} + +Please review the TODO comments in the files and provide the missing information. + +{END IF} + +{IF IS_NEW_LANGUAGE = true} + +**⚠️ New language detected** + +This appears to be a NEW LANGUAGE, not just a new package manager: +- [ ] Review the new language entry added to `data/tables/supported-code-languages.yml`, which is the source for `content/get-started/learning-about-github/github-language-support.md` + - Confirm `depUpdates` is `{Display Name}` + - Confirm `depGraph` and all other feature support values +- [ ] Check if dependency scope is supported for this language + - If YES: Update `data/reusables/dependabot/dependabot-alerts-dependency-scope.md` + +{END IF} + +**Additional updates to review:** + +This PR addresses the core Dependabot ecosystem documentation. Based on the [ongoing content design workflow](https://github.com/github/docs-content/blob/main/.github/workflows/ongoing-content-design-plan.yml), please check if these additional updates apply: + +{IF PRIVATE_REGISTRIES_SUPPORTED = true} +- [ ] **Private registries guide**: A TODO comment has been added to `configure-private-registries.md` for configuration examples +{ENDIF} + +{IF PRIVATE_REGISTRIES_SUPPORTED = unknown} +- [ ] **Confirm private registry support**: If supported, update the table entry and add a configuration TODO to `configure-private-registries.md`. If not supported, update only the table entry +{ENDIF} + +{IF IS_NEW_LANGUAGE = unknown} +- [ ] **Verify language**: Please confirm if `{Language}` is a new language or already present in `data/tables/supported-code-languages.yml` +{ENDIF} + + +### Check off the following: + +- [ ] A subject matter expert (SME) has reviewed the technical accuracy of the content in this PR. +- [ ] The changes in this PR meet [the docs fundamentals](http://docs.github.com/en/contributing/writing-for-github-docs/about-githubs-documentation-fundamentals). +- [ ] All CI checks are passing and the changes look good in the review environment. +``` + +**Notes:** +- Replace `{username}` with the person who assigned the issue +- Replace `{issue_number}` with the docs-content issue number +- If you found a good reference PR, mention it in "following the pattern from PR #..." +- Use ✅ or ❌ emoji for confirmed supported/not supported values in the details list; use TODO for unknown values +- The "Missing Information" section should only appear if there are TODO comments in the files +- The "New Language Detected" section only appears if `IS_NEW_LANGUAGE = true` +- The "Additional Updates to Review" section includes conditionals based on your flags + +**PR status:** +- If ALL required information is present AND no special cases: Create as **ready for review** +- If ANY required information is missing OR new language OR private registries need attention: Create as **DRAFT** + +### Step 10: Post comment (if missing data) + +If you created a DRAFT PR due to missing information, add a comment to the PR: + +```markdown +I've created this draft PR based on the available information from the issue. However, I couldn't extract the following details: + +{LIST MISSING FIELDS} + +Please provide this information so I can complete the documentation. You can: +1. Add the details as a comment here +2. Update the files directly +3. Tag someone who knows (@stakeholder from the issue) + +Once the information is provided, I can update the PR and mark it ready for review. +``` + +If the GHES version is missing, the comment must include: + +```markdown +The first supported GHES version is required for the feature flag and needs to be confirmed from the docs-content or releases issue. +``` + +If private registry support is unknown, the comment must include: + +```markdown +Please confirm whether private registries are supported for this ecosystem. If they are supported, the PR also needs a TODO in `configure-private-registries.md` for the required configuration documentation. +``` + +## Important notes + +### Style and formatting + +- **Bullet lists:** Use asterisks (`*`), not hyphens (`-`) +- **Liquid variables:** Use `{% data variables.product.prodname_dependabot %}` for "Dependabot" +- **Table alignment:** Match the existing table formatting exactly +- **Alphabetical order:** Critical! Insert new entries in the correct alphabetical position +- **Feature flags:** Always wrap new content in `{% ifversion dependabot-{yaml-value}-support %}` + +### Common pitfalls to avoid + +- **Don't hardcode file paths** - use glob/grep to find current locations +- **Don't skip the feature flag** - it's required for version gating +- **Don't default the GHES version** - source it from the docs-content or releases issue, or leave a TODO and request confirmation in a PR comment +- **Don't infer private registry support** - use only explicit issue information; unknown support stays as a table TODO and does not trigger a change to `configure-private-registries.md` +- **Don't forget alphabetical order** - tables must stay sorted +- **Don't use inconsistent octicons** - match the aria-label pattern exactly +- **Don't create ready-for-review PRs with TODOs** - use draft status +- **Don't skip the scope detection** - new language vs. ecosystem matters + +### Validation before creating PR + +Before you create the PR, verify: +1. ✅ Feature flag file created with correct YAML value +2. ✅ GHES version matches the docs-content or releases issue, or the feature flag contains a TODO and the PR has a comment requesting confirmation +3. ✅ All 4 core files updated (or TODO comments explain why not) +4. ✅ Private registry support came from explicit issue information, or the table contains a TODO and the PR comment requests confirmation +5. ✅ `configure-private-registries.md` was changed only when private registry support was explicitly confirmed +6. ✅ All table entries in alphabetical order +7. ✅ Cooldown entries contain all 3 columns, including separate default-days and SemVer-bump support values +8. ✅ Dependency graph entries contain all 7 columns, including {% data variables.product.prodname_dependabot %} graph jobs +9. ✅ All `ifversion` tags have matching `endif` tags +10. ✅ Octicon syntax is correct +11. ✅ PR description accurately lists what changed +12. ✅ Draft status if ANY TODOs present +13. ✅ Scope flags (IS_NEW_LANGUAGE, PRIVATE_REGISTRIES_SUPPORTED) were set +14. ✅ `data/tables/supported-code-languages.yml` was updated when language support changed; the rendered article was not edited directly +15. ✅ Workflow checklist linked in PR description + +## Examples + +### Example 1: Complete information (Deno) + +**Input:** Issue with all details provided, Deno uses TypeScript/JavaScript, private registries not supported + +**Flags set:** +- `IS_NEW_LANGUAGE = false` +- `PRIVATE_REGISTRIES_SUPPORTED = false` + +**Output:** +- Feature flag: `data/features/dependabot-deno-support.yml` +- All 4 core files updated with complete information +- No private registries TODO (not supported) +- No new language note +- Ready-for-review PR with full description +- No TODO comments + +### Example 2: Missing information + private registries + +**Input:** Issue missing some details, ecosystem supports private registries + +**Flags set:** +- `IS_NEW_LANGUAGE = false` +- `PRIVATE_REGISTRIES_SUPPORTED = true` + +**Output:** +- Feature flag: Created +- Tables: Updated with `` in cells with missing data +- Private registries guide: TODO comment added +- **Draft PR** with "Missing Information" section +- PR checklist includes private registries guide item +- Comment posted listing what's needed + +### Example 3: New language detected + +**Input:** Issue for a brand new language (hypothetical: Zig) + +**Flags Set:** +- `IS_NEW_LANGUAGE = true` +- `PRIVATE_REGISTRIES_SUPPORTED = false` + +**Output:** +- Feature flag: Created +- All 4 core files and `data/tables/supported-code-languages.yml` updated +- **Draft PR** with "New Language Detected" section +- `data/tables/supported-code-languages.yml` updated with the new language and known feature support +- PR includes checklist for any unconfirmed language feature values and the dependency scope reusable +- No private registries changes (not supported) + +## Error handling + +If you encounter issues: + +**Files not found:** +- Use glob to search more broadly +- Report in PR comment which files couldn't be located +- Do NOT proceed if critical files are missing + +**Cannot determine alphabetical position:** +- List the surrounding entries +- Ask for clarification in PR comment + +**Conflicting information:** +- Note the conflict in TODO comment +- List sources in PR comment +- Default to more conservative option (e.g., "not supported" if unclear) + +**Cannot access linked release issue:** +- Proceed with information from docs-content issue only +- Note in PR that release issue couldn't be accessed +- Mark uncertain fields with TODO + +**Unclear if new language:** +- Set `IS_NEW_LANGUAGE = unknown` +- Add verification note in PR description +- Mark PR as draft + +## Success criteria + +Your work is successful when: +- ✅ All 4 core files are updated consistently +- ✅ Tables remain in alphabetical order +- ✅ Feature flag exists and is referenced correctly +- ✅ PR description is complete and accurate +- ✅ Missing data is clearly marked with TODOs +- ✅ PR status (draft/ready) matches data completeness +- ✅ Issue is properly linked with "Closes" syntax +- ✅ Update scope correctly identified (new language vs new ecosystem) +- ✅ Private registries guide flagged if applicable +- ✅ `data/tables/supported-code-languages.yml` updated or flagged for verification if language support changes +- ✅ Workflow checklist linked for reviewer reference diff --git a/.github/workflows/check-for-spammy-issues.yml b/.github/workflows/check-for-spammy-issues.yml index 74f9c7f519d8..ceeb08346232 100644 --- a/.github/workflows/check-for-spammy-issues.yml +++ b/.github/workflows/check-for-spammy-issues.yml @@ -30,6 +30,7 @@ jobs: const titleWordCountMin = 3 const urlRegex = /https?:\/\/\S+/i const titleHasUrl = urlRegex.test(issue.title) + const titleHasDollarSign = issue.title.includes('$') try { await github.rest.teams.getMembershipForUserInOrg({ @@ -45,7 +46,7 @@ jobs: // An error will be thrown if the user is not a GitHub employee // If a user is not a GitHub employee, we should check to see if title has at least the minimum required number of words in it and if it does, we can exit the workflow - if (titleWordCount >= titleWordCountMin && !titleHasUrl) { + if (titleWordCount >= titleWordCountMin && !titleHasUrl && !titleHasDollarSign) { return } } diff --git a/.github/workflows/send-to-triage-board.yml b/.github/workflows/send-to-triage-board.yml new file mode 100644 index 000000000000..f5defa974e68 --- /dev/null +++ b/.github/workflows/send-to-triage-board.yml @@ -0,0 +1,45 @@ +name: Add new issues and PRs to central triage board + +# **What it does**: Adds newly opened or reopened issues and pull requests in github/docs to the right place for triage, and stamps the item with today's date. +# **Why we have it**: To ensure incoming work in the public docs repo is triaged properly. +# **Who does it impact**: Writers, FRs. + +on: + issues: + types: [opened, reopened] + pull_request_target: + types: [opened, reopened, ready_for_review] + +permissions: + contents: read + +jobs: + add-to-central-triage: + runs-on: ubuntu-latest + if: github.repository == 'github/docs' + steps: + - name: Triage to central triage board + env: + GITHUB_TOKEN: ${{ secrets.DOCS_BOT_PAT_BASE }} + ITEM_URL: ${{ github.event.issue.html_url || github.event.pull_request.html_url }} + # Add to the Central Triage Group project board and set date to now + PROJECT_NUMBER: '19598' + PROJECT_ID: 'PVT_kwDNJr_OAJ4AfQ' + DATE_FIELD_ID: 'PVTF_lADNJr_OAJ4Afc4IAbbv' + run: | + echo "Adding $ITEM_URL to project $PROJECT_NUMBER..." + ITEM_ID=$(gh project item-add "$PROJECT_NUMBER" --owner github --url "$ITEM_URL" --format json --jq '.id' || true) + + sleep 10 + + if [ -n "$ITEM_ID" ] && [ "$ITEM_ID" != "null" ]; then + echo "Editing date on item $ITEM_ID..." + DATE=$(date '+%Y-%m-%d') + if gh project item-edit --project-id "$PROJECT_ID" --id "$ITEM_ID" --field-id "$DATE_FIELD_ID" --date "$DATE"; then + echo "done editing" + else + echo "::warning::gh project item-edit failed for $ITEM_URL (item $ITEM_ID); the item is on the board but the date field was not set" + fi + else + echo "::warning::gh project item-add did not return an item id for $ITEM_URL; skipping item-edit" + fi diff --git a/content/copilot/concepts/agents/copilot-cli/about-copilot-cli.md b/content/copilot/concepts/agents/copilot-cli/about-copilot-cli.md index 014ba043ea21..f81a62d9f14b 100644 --- a/content/copilot/concepts/agents/copilot-cli/about-copilot-cli.md +++ b/content/copilot/concepts/agents/copilot-cli/about-copilot-cli.md @@ -80,7 +80,7 @@ You can start a {% data variables.copilot.copilot_cli_short %} session inside an To start a cloud-backed session, run: ```bash copy -copilot ‑‑cloud +copilot --cloud ``` ## Use cases for {% data variables.copilot.copilot_cli %} diff --git a/content/copilot/how-tos/copilot-cli/automate-copilot-cli/schedule-prompts.md b/content/copilot/how-tos/copilot-cli/automate-copilot-cli/schedule-prompts.md index 820670f89949..f16316b5ca8f 100644 --- a/content/copilot/how-tos/copilot-cli/automate-copilot-cli/schedule-prompts.md +++ b/content/copilot/how-tos/copilot-cli/automate-copilot-cli/schedule-prompts.md @@ -73,7 +73,7 @@ The prompt fires once, after the delay has elapsed, and is then removed from the You can use `/every` and `/after` to schedule a skill. To do this, you can reference the skill explicitly by using its slash command, or you can use natural language to tell {% data variables.product.prodname_copilot_short %} to run the skill. > [!NOTE] -> Only user-invocable skills can be scheduled this way. You cannot include built-in slash commands (such as `/clear`) in a scheduled prompt. +> Only user-invocable skills and a subset of built-in slash commands can be scheduled. Commands that start a self-contained piece of work—such as `/plan`, `/review`, `/research`, or `/security-review`—are schedulable. Commands that change your session or configuration (for example, `/model`, `/clear`, `/compact`, `/permissions`, or `/sandbox`), that only display information (such as `/usage` or `/context`), or that manage scheduling itself (`/every` and `/after`) can't be scheduled, and {% data variables.product.prodname_copilot_short %} rejects them when you try. ### Examples @@ -94,9 +94,11 @@ You can use `/every` and `/after` to schedule a skill. To do this, you can refer | `h` | hours | `2h` | | `d` | days | `1d` | -A bare number with no suffix is interpreted as minutes—for example, `/every 30 remind me to check for Slack messages` schedules the prompt every 30 minutes. +When you specify a numeric duration, always include the suffix. A bare number—for example, `/every 30 remind me to check for Slack messages`—is not recognized as an interval. -The minimum interval is **10 seconds** and the maximum is **1 day** (24 hours). +For a fixed interval, the minimum is **10 seconds** and the maximum is **1 day** (24 hours). + +You can also describe the timing in plain language instead of using a duration—for example, `/after at 3pm push the release`, or `/every day at 9am post the standup`. {% data variables.product.prodname_copilot_short %} uses a model to interpret the phrase, then creates the schedule from it. ## Identifying scheduled prompts in the session @@ -116,9 +118,9 @@ Press Esc to exit the schedule list. Scheduled prompts are scoped to the session they were created in, and they are only triggered while that session is running. -When you reopen the session (using the `--continue` or `--resume` command line options) the schedules are restarted, with interval before a schedule is triggered measured from the moment you reopen the session. +When you reopen the session (using the `--continue` or `--resume` command line options) the schedules are restored. For a recurring schedule created with a fixed interval, the wait before the next run is measured from the moment you reopen the session. -If an `/after` schedule had not been triggered before you closed the session, it remains in the schedule list and will be triggered after the specified delay in the reopened session. +An `/after` schedule that had not been triggered before you closed the session keeps its original target time, rather than restarting the delay. If that time passed while the session was closed, the prompt is submitted as soon as you reopen the session. ## Running a prompt from an external scheduler diff --git a/content/copilot/how-tos/copilot-cli/set-up-copilot-cli/authenticate-copilot-cli.md b/content/copilot/how-tos/copilot-cli/set-up-copilot-cli/authenticate-copilot-cli.md index ee3130ff8d29..852b0cfb149c 100644 --- a/content/copilot/how-tos/copilot-cli/set-up-copilot-cli/authenticate-copilot-cli.md +++ b/content/copilot/how-tos/copilot-cli/set-up-copilot-cli/authenticate-copilot-cli.md @@ -18,9 +18,9 @@ If you use your own LLM provider API keys (BYOK), {% data variables.product.gith Authentication is required for any other {% data variables.copilot.copilot_cli %} usage. -When authentication is required, {% data variables.copilot.copilot_cli_short %} supports three methods. The method you use depends on whether you are working interactively or in an automated environment. +When authentication is required, {% data variables.copilot.copilot_cli_short %} supports several methods. The method you use depends on whether you are working interactively or in an automated environment. -* **OAuth device flow**: The default and recommended method for interactive use. When you run `/login` in {% data variables.copilot.copilot_cli_short %}, the CLI generates a one-time code and directs you to authenticate in your browser. This is the simplest way to authenticate. See [Authenticating with OAuth](#authenticating-with-oauth). +* **OAuth**: The default and recommended method for interactive use. There are two OAuth flows. The browser (web) flow opens your browser to authorize the sign-in and completes it on a local loopback callback. The device code flow displays a one-time code that you enter in your browser. The browser flow is the default on a local desktop, and known remote or headless environments (including SSH, {% data variables.product.prodname_github_codespaces %}, dev containers, and CI) default to the device code flow. See [Authenticating with OAuth](#authenticating-with-oauth). * **Environment variables**: Recommended for CI/CD pipelines, containers, and non-interactive environments. You set a supported token as an environment variable (`COPILOT_GITHUB_TOKEN`, `GH_TOKEN`, or `GITHUB_TOKEN`), and the CLI uses it automatically without prompting. See [Authenticating with environment variables](#authenticating-with-environment-variables). * **{% data variables.product.prodname_cli %} fallback**: If you have {% data variables.product.prodname_cli %} (`gh`) (note: the `gh` CLI, not `copilot`) installed and authenticated, {% data variables.copilot.copilot_cli_short %} can use its token automatically. This is the lowest priority method and activates only when no other credentials are found. See [Authenticating with {% data variables.product.prodname_cli %}](#authenticating-with-github-cli). @@ -52,7 +52,7 @@ Offline mode is **only fully air-gapped** if your BYOK provider is local or othe | Token type | Prefix | Supported | Notes | |----------------------------|---------------|-----------|--------------------------------------------------------| -| OAuth token (device flow) | `gho_` | Yes | Default method via `copilot login` | +| OAuth token (browser or device flow) | `gho_` | Yes | Default method via `copilot login` | | Fine-grained PAT | `github_pat_` | Yes | Must be owned by your personal account (not an organization) with the **{% data variables.product.prodname_copilot_short %} Requests** account permission | | GitHub App user-to-server | `ghu_` | Yes | Via environment variable | | Classic PAT | `ghp_` | No | Not supported by {% data variables.copilot.copilot_cli_short %} | @@ -78,12 +78,12 @@ When you run a command, {% data variables.copilot.copilot_cli_short %} checks fo 1. GitHub CLI (`gh auth token`) fallback > [!NOTE] -> * An environment variable silently overrides a stored OAuth token. If you set `GH_TOKEN` for another tool, the CLI uses that token instead of the OAuth token from `copilot login`. To avoid unexpected behavior, unset environment variables you do not intend the CLI to use. +> * An environment variable silently overrides a stored OAuth token. If you set `GH_TOKEN` for another tool, the CLI uses that token instead of the OAuth token from `copilot login`. To avoid unexpected behavior, unset environment variables you do not intend the CLI to use. There is one exception: in {% data variables.product.prodname_github_codespaces %}, the `GITHUB_TOKEN` that is injected automatically does not take precedence over an account you signed in with using `/login`. A `GITHUB_TOKEN`, `COPILOT_GITHUB_TOKEN`, or `GH_TOKEN` that you export explicitly still does. > * When you configure BYOK provider environment variables (for example, `COPILOT_PROVIDER_BASE_URL`, `COPILOT_PROVIDER_API_KEY`), {% data variables.copilot.copilot_cli_short %} uses these for AI model requests regardless of your {% data variables.product.github %} authentication status. {% data variables.product.github %} tokens are only needed for {% data variables.product.github %}-hosted features. ## Authenticating with OAuth -The OAuth device flow is the default authentication method for interactive use. You can authenticate by running `/login` from {% data variables.copilot.copilot_cli_short %} or `copilot login` from your terminal. +OAuth is the default authentication method for interactive use. You can authenticate by running `/login` from {% data variables.copilot.copilot_cli_short %} or `copilot login` from your terminal. Both offer a browser (web) flow and a device code flow. ### Authenticate with `/login` @@ -101,16 +101,28 @@ The OAuth device flow is the default authentication method for interactive use. 2. {% data variables.product.prodname_ghe_cloud %} with data residency (*.ghe.com) ``` -1. The CLI displays a one-time user code and automatically copies it to your clipboard and opens your browser. +1. Choose how you want to sign in. The recommended option is listed first, and depends on your environment: the browser flow on a local terminal, or the device code flow in a remote or headless environment. The following example shows the prompt in a local terminal: ```text - Waiting for authorization... - Enter one-time code: 1234-5678 at https://github.com/login/device - Press any key to copy to clipboard and open browser... + How do you want to sign in? + 1. Sign in with your browser (recommended) + 2. Sign in with a device code ``` -1. Navigate to the verification URL at `https://github.com/login/device` if your browser did not open automatically. -1. Paste the one-time code in the field on the page. +1. Complete the flow you selected. + + * **Browser**: {% data variables.copilot.copilot_cli_short %} opens your browser so that you can authorize the sign-in. If your browser does not open automatically, the terminal displays a URL that you can visit instead. + + * **Device code**: The CLI displays a one-time user code, and can copy it to your clipboard and open your browser for you. + + ```text + Waiting for authorization... + Enter one-time code: 1234-5678 at https://github.com/login/device + Press any key to copy to clipboard and open browser... + ``` + + Navigate to the verification URL at `https://github.com/login/device` if your browser did not open automatically, then paste the one-time code in the field on the page. + 1. If your organization uses SAML SSO, click **Authorize** next to each organization you want to grant access to. 1. Review the requested permissions and click **Authorize GitHub Copilot CLI**. 1. Return to your terminal. The CLI displays a success message when authentication is complete. @@ -133,14 +145,27 @@ The OAuth device flow is the default authentication method for interactive use. copilot login --host HOSTNAME ``` - The CLI displays a one-time user code and automatically copies it to your clipboard and opens your browser. +1. Authorize the sign-in. + + On a local desktop, `copilot login` uses the browser flow by default. It opens your browser to authorize the sign-in and captures the result on a local loopback callback. + + ```text + Opening your browser to authenticate... + If it doesn't open automatically, visit: + URL + Waiting for authorization... + ``` + + Known remote or headless environments (including SSH, {% data variables.product.prodname_github_codespaces %}, dev containers, and CI) use the device code flow instead. The CLI displays a one-time code and, when supported by the environment, can copy it to your clipboard and open a browser. ```text - To authenticate, visit https://github.com/login/device and enter code 1234-5678. + To authenticate, visit https://github.com/login/device and enter code 1234-5678 + Waiting for authorization... ``` -1. Navigate to the verification URL at `https://github.com/login/device` if your browser did not open automatically. -1. Paste the one-time code in the field on the page. + To force a particular flow, add the `--web-flow` or `--device-code` option. + +1. Navigate to the URL displayed in your terminal if your browser did not open automatically. For the device code flow, paste the one-time code in the field on the page. 1. If your organization uses SAML SSO, click **Authorize** next to each organization you want to grant access to. 1. Review the requested permissions and click **Authorize GitHub Copilot CLI**. 1. Return to your terminal. The CLI displays a success message when authentication is complete. diff --git a/content/copilot/how-tos/copilot-cli/set-up-copilot-cli/troubleshoot-copilot-cli-auth.md b/content/copilot/how-tos/copilot-cli/set-up-copilot-cli/troubleshoot-copilot-cli-auth.md index c122abb364f6..e229d3cc8655 100644 --- a/content/copilot/how-tos/copilot-cli/set-up-copilot-cli/troubleshoot-copilot-cli-auth.md +++ b/content/copilot/how-tos/copilot-cli/set-up-copilot-cli/troubleshoot-copilot-cli-auth.md @@ -62,7 +62,7 @@ If you are using an environment variable, check whether the `COPILOT_GITHUB_TOKE If the command prints nothing, the variable is not set. Set the variable to a valid token. To generate a token, see [AUTOTITLE](/copilot/how-tos/copilot-cli/set-up-copilot-cli/authenticate-copilot-cli#authenticating-with-environment-variables). ```bash copy - export $COPILOT_GITHUB_TOKEN=PERSONAL_ACCESS_TOKEN + export COPILOT_GITHUB_TOKEN=PERSONAL_ACCESS_TOKEN ``` #### macOS keychain @@ -106,7 +106,31 @@ Review the token's status and permissions on {% data variables.product.prodname_ ## {% data variables.product.pat_classic_caps %} rejected -A token starting with `ghp_` is silently ignored and the CLI behaves as if no token is set. +A token starting with `ghp_` is rejected. What happens next depends on how you are running {% data variables.copilot.copilot_cli_short %}. + +In an interactive session, the classic {% data variables.product.pat_generic %} is ignored and the CLI keeps running, so you can authenticate another way, such as with `/login`. {% data variables.copilot.copilot_cli_short %} displays a warning like the following, naming the environment variable that holds the token: + + +```text +Classic Personal Access Tokens (ghp_) are not supported. GITHUB_TOKEN contains a classic PAT and will be ignored. Use /login to authenticate, or replace it with a fine-grained PAT. +``` + + +In non-interactive use, such as `copilot -p` or other automation, if the classic {% data variables.product.pat_generic %} is the only credential available, the CLI refuses to start and displays the following error, naming the environment variable that holds the token: + + +```text +Error: Classic Personal Access Tokens (ghp_) are not supported by Copilot. + +The GITHUB_TOKEN environment variable contains a classic PAT. +Please use a Fine-Grained Personal Access Token or another authentication method. + +To fix this, you can: + • Replace the token in GITHUB_TOKEN with a fine-grained PAT + • Unset GITHUB_TOKEN and run 'gh auth login' to authenticate + • Unset GITHUB_TOKEN and start 'copilot', then use the '/login' command +``` + ### Cause diff --git a/content/copilot/how-tos/copilot-cli/use-copilot-cli-in-actions.md b/content/copilot/how-tos/copilot-cli/use-copilot-cli-in-actions.md index 45e3320c7024..4bed4fdba593 100644 --- a/content/copilot/how-tos/copilot-cli/use-copilot-cli-in-actions.md +++ b/content/copilot/how-tos/copilot-cli/use-copilot-cli-in-actions.md @@ -50,19 +50,22 @@ jobs: runs-on: ubuntu-latest steps: - uses: {% data reusables.actions.action-checkout %} + with: + fetch-depth: 2 - name: Install Copilot CLI run: npm install -g @github/copilot - name: Run Copilot - run: copilot --yolo -p "Summarize the changes in this commit" + run: copilot -p "Use git show HEAD to summarize the changes in this commit" -s --allow-tool='shell(git show:*)' env: GITHUB_TOKEN: {% raw %}${{ github.token }}{% endraw %} ``` Key details about this example: -* The `--yolo` flag automatically approves all tool, path, and URL permission requests. Non-interactive (`-p`) runs can't display an interactive approval prompt, so any action that isn't pre-approved is denied automatically. To grant only the permissions the task needs, use narrower options such as `--allow-tool`, `--add-dir`, and `--allow-url` instead. +* The `fetch-depth: 2` option fetches the current commit and its parent, allowing `git show HEAD` to calculate the changes introduced by the current commit. +* The `--allow-tool='shell(git show:*)'` option allows {% data variables.copilot.copilot_cli_short %} to run `git show` commands without requesting approval. Non-interactive (`-p`) runs can't display an interactive approval prompt, so any action that isn't pre-approved is denied automatically. * The `copilot-requests: write` permission is required for the workflow to make {% data variables.product.prodname_copilot_short %} requests. -* The `GITHUB_TOKEN` provided by {% data variables.product.prodname_actions %} handles authentication automatically, no additional secrets are needed. +* The `GITHUB_TOKEN` provided by {% data variables.product.prodname_actions %} handles authentication automatically. No additional secrets are needed. > [!NOTE] > You must be on a recent version of {% data variables.copilot.copilot_cli_short %} to use `GITHUB_TOKEN` authentication. Update with `copilot update`, or reinstall the latest version with `npm install -g @github/copilot`. diff --git a/content/copilot/how-tos/copilot-cli/use-copilot-cli/ask-a-side-question.md b/content/copilot/how-tos/copilot-cli/use-copilot-cli/ask-a-side-question.md new file mode 100644 index 000000000000..c5c4faf1aaed --- /dev/null +++ b/content/copilot/how-tos/copilot-cli/use-copilot-cli/ask-a-side-question.md @@ -0,0 +1,42 @@ +--- +title: Asking a side question in {% data variables.copilot.copilot_cli %} +shortTitle: Ask a side question +intro: During a CLI session, you can ask {% data variables.product.prodname_copilot_short %} a question without adding the prompt, or the answer, to your conversation history. +product: '{% data reusables.gated-features.copilot-cli %}' +versions: + feature: copilot +contentType: how-tos +category: + - Build with Copilot CLI +docsTeamMetrics: + - copilot-cli +--- + +During an interactive {% data variables.copilot.copilot_cli_short %} session, you can use the `/ask` slash command to ask a quick side question and see the answer in a separate dialog. {% data variables.product.prodname_copilot_short %} uses the current conversation as context when it is available, but cannot use tools to answer the question. + +You can use `/ask` while {% data variables.product.prodname_copilot_short %} is currently working on a task. The question and answer are not added to the conversation history, so you should use a normal prompt instead if you want them to become part of the conversation. + +The `/ask` command is not available for remote sessions. + +## Asking a quick question + +1. In a local interactive session, enter `/ask` followed by your question. + + For example: + + ```copilot copy + /ask What does the previous response mean by "idempotent"? + ``` + + > [!NOTE] + > `/btw` is an alias for `/ask`. You can use either command to ask a side question. + + {% data variables.product.prodname_copilot_short %} answers your question in a dialog, separate from the main conversation. + +1. To cancel an answer that is still being generated, or to dismiss a completed answer, press Esc. + +The dialog does not have an input field for follow-up questions. To ask another question, dismiss the dialog and enter another `/ask YOUR-QUESTION` command. + +## Further reading + +* [AUTOTITLE](/copilot/reference/copilot-cli-reference/cli-command-reference#slash-commands-in-the-interactive-interface) diff --git a/content/copilot/how-tos/copilot-cli/use-copilot-cli/browse-issues-prs-gists.md b/content/copilot/how-tos/copilot-cli/use-copilot-cli/browse-issues-prs-gists.md index 3393158323d8..3d2c4db07bd5 100644 --- a/content/copilot/how-tos/copilot-cli/use-copilot-cli/browse-issues-prs-gists.md +++ b/content/copilot/how-tos/copilot-cli/use-copilot-cli/browse-issues-prs-gists.md @@ -48,7 +48,7 @@ The **Issues**, **Pull requests**, and **Gists** tabs all use the same controls. * Press Enter to display a detailed view of the highlighted item. Press Esc in the details view to return to the list. * Press o to open the highlighted item (or, in the detailed view, the current item) on {% data variables.product.prodname_dotcom_the_website %}. * Press c to insert a reference to the item into the prompt input area and jump back to the **Session** tab. -* Press / (on the **Issues** and **Pull requests** tabs) to search {% data variables.product.prodname_dotcom %} with a custom query. Type a query, press Enter to run it, and Esc to cancel or clear it. +* Press / (on the **Issues** and **Pull requests** tabs) to filter the list with your own search terms. Type your terms, press Enter to run the search, and Esc to cancel or clear it. For the full set of keypresses you can use, see [Keyboard reference](#keyboard-reference) at the end of this article. @@ -80,11 +80,11 @@ Pressing c inserts a reference to the pull request into the prompt bo By default, the **Issues** and **Pull requests** tabs show items that involve you. Press a to toggle between this (`involves:@me`) and all open items. -To run your own search, press /. An inline search box opens where you can type a {% data variables.product.prodname_dotcom %} search query, then press Enter to run it. +To run your own search, press /. An inline search box opens where you can type your search terms, then press Enter to run the search. Press Esc to cancel while typing, or to clear an applied search and return to the default list. -You can use the same set of search qualifiers that are available on {% data variables.product.prodname_dotcom_the_website %}. See [AUTOTITLE](/search-github/searching-on-github/searching-issues-and-pull-requests). +Your search terms are added to the qualifiers the tab already applies, so results are always limited to open items in the current repository—and, unless you have pressed a, to items that involve you. Enter plain search terms rather than search qualifiers: text containing a colon is searched for as a literal phrase, so a term such as `label:bug` is not interpreted as a qualifier. ## Browsing your gists diff --git a/content/copilot/how-tos/copilot-cli/use-copilot-cli/index.md b/content/copilot/how-tos/copilot-cli/use-copilot-cli/index.md index 2972d9f58236..78133051eb4d 100644 --- a/content/copilot/how-tos/copilot-cli/use-copilot-cli/index.md +++ b/content/copilot/how-tos/copilot-cli/use-copilot-cli/index.md @@ -13,6 +13,7 @@ children: - /connecting-vs-code - /delegate-tasks-to-cca - /browse-issues-prs-gists + - /ask-a-side-question - /roll-back-changes - /work-with-multiple-sessions - /invoke-custom-agents diff --git a/content/copilot/how-tos/copilot-cli/use-copilot-cli/manage-pull-requests.md b/content/copilot/how-tos/copilot-cli/use-copilot-cli/manage-pull-requests.md index 0d5a0e4ac9de..b8c37a1134a9 100644 --- a/content/copilot/how-tos/copilot-cli/use-copilot-cli/manage-pull-requests.md +++ b/content/copilot/how-tos/copilot-cli/use-copilot-cli/manage-pull-requests.md @@ -89,6 +89,12 @@ The `/pr` slash command has several subcommands that you can use to perform diff No Yes + +/pr automerge +Do the same as /pr auto, then merge the pull request once it is green. Find out more +No +Yes + @@ -142,6 +148,8 @@ To have {% data variables.product.prodname_copilot_short %} read and address rev {% data variables.product.prodname_copilot_short %} fetches all review comment threads on the pull request, determines what changes are requested, applies the changes to your codebase, and commits and pushes the fixes. Actionable code change requests are prioritized over conversational comments. +For each thread it addresses, {% data variables.product.prodname_copilot_short %} replies within the thread on {% data variables.product.prodname_dotcom_the_website %} to explain the change, then marks the thread as resolved. Threads that need your input are answered but left unresolved. + ## Resolving merge conflicts To sync your branch with the base branch and resolve any merge conflicts, enter: @@ -201,7 +209,9 @@ To have {% data variables.product.prodname_copilot_short %} manage the entire pu /pr auto ``` -If no pull request exists for the current branch, {% data variables.product.prodname_copilot_short %} creates one first. It then loops through the fix phases—review feedback, conflicts, and CI—repeating until there are no more review comments, no conflicts, and all CI checks pass. +If no pull request exists for the current branch, {% data variables.product.prodname_copilot_short %} creates one first. It then loops through the fix phases—review feedback, conflicts, and CI—repeating until there are no more review comments, no conflicts, and all CI checks pass. It does not merge the pull request. + +The loop runs as a self-paced schedule rather than as a single, continuous turn, doing one pass of work each time it runs and pausing between passes while CI settles. Use the `/every` slash command to check on the loop, or to stop it. You can append instructions to guide the pull request creation. For example: @@ -209,6 +219,18 @@ You can append instructions to guide the pull request creation. For example: /pr auto include migration notes in the description ``` +### Automatically merging the pull request + +`/pr auto` deliberately stops when the pull request is green. If you also want {% data variables.product.prodname_copilot_short %} to merge the pull request, enter: + +```copilot copy +/pr automerge +``` + +This runs the same loop as `/pr auto`. Once the pull request is no longer a draft, has no unresolved requests for changes, and all required checks are passing, {% data variables.product.prodname_copilot_short %} enables auto-merge rather than merging the pull request itself. {% data variables.product.prodname_dotcom %} then completes the merge as soon as every remaining requirement is satisfied, including any required approvals and merge queue. {% data variables.product.prodname_copilot_short %} keeps the loop running—handling any further review feedback or check failures—until the pull request is merged or closed. + +You can use `/pr agentmerge` as an alias for `/pr automerge`. + ## Further reading * [AUTOTITLE](/copilot/how-tos/copilot-cli/use-copilot-cli/allowing-tools) diff --git a/content/copilot/how-tos/copilot-cli/use-copilot-cli/voice-input.md b/content/copilot/how-tos/copilot-cli/use-copilot-cli/voice-input.md index 2906a434e7dd..354528f219b7 100644 --- a/content/copilot/how-tos/copilot-cli/use-copilot-cli/voice-input.md +++ b/content/copilot/how-tos/copilot-cli/use-copilot-cli/voice-input.md @@ -20,7 +20,7 @@ You need a working microphone connected to your machine. By default, voice input ## Limitation -Voice input is currently only supported for English and Spanish dictation. English is the default language for speech recognition. +{% data variables.copilot.copilot_cli_short %} offers a fixed set of speech-to-text models: a multilingual model, which is the default, plus a dedicated English model and a dedicated Spanish model. Only these models are listed in the voice models picker. ## Enabling voice input @@ -31,12 +31,12 @@ Before you can dictate prompts, you need to download the voice runtime that powe The download runs in the background. You can keep using {% data variables.copilot.copilot_cli_short %} while it completes. -1. When you're prompted to choose a voice model, press Enter with "Download default model" selected to download the English speech-to-text model. +1. When you're prompted to choose a voice model, press Enter with "Download default model" selected to download the default multilingual speech-to-text model. - Alternatively, if you want to dictate in Spanish: + Alternatively, if you want to use the dedicated English or Spanish model: 1. Use the arrow keys on your keyboard to select "Browse models", then press Enter. - 1. In the voice models picker, use the arrow keys to select the Spanish speech-to-text model, then press Enter to download it. + 1. In the voice models picker, use the arrow keys to select the model you want, then press Enter to download it. 1. Press Esc to exit the picker. ## Using voice input @@ -92,7 +92,7 @@ If you have more than one microphone available on your system, you can switch in ## Switching voice models -You can dictate prompts in English or Spanish, but the appropriate voice model must be downloaded and activated for the language you want to use. +The default multilingual model handles more than one language, but you can switch to the dedicated English or Spanish model if you prefer. The model you want must be downloaded and activated before you can use it. To change to a different voice model: @@ -100,7 +100,7 @@ To change to a different voice model: The voice models picker is displayed. A check mark indicates the currently active model. -1. In the voice models picker, use the arrow keys on your keyboard to select the English or Spanish speech-to-text, then press Enter. +1. In the voice models picker, use the arrow keys on your keyboard to select the model you want to use, then press Enter. If the model is not already downloaded, it will be downloaded to your machine. diff --git a/content/copilot/reference/ai-models/model-comparison.md b/content/copilot/reference/ai-models/model-comparison.md index 6fb5654f718b..1a9a81fa8558 100644 --- a/content/copilot/reference/ai-models/model-comparison.md +++ b/content/copilot/reference/ai-models/model-comparison.md @@ -140,7 +140,7 @@ Some models have behaviors, limitations, or safeguards that are useful to unders ### {% data variables.copilot.copilot_kimi_k3 %} -{% data variables.copilot.copilot_kimi_k3 %} is designed for long-context, multi-step coding and agentic workflows. In pre-release testing, the model exhibited elevated risk on certain higher-risk prompts and was less consistent than some other models in refusing requests involving sensitive topics. These behaviors may reflect differences in the model's safety post-training and alignment. We have deployed additional safeguards in {% data variables.product.prodname_copilot %} to help mitigate the identified risks. As with any model, enterprises should evaluate model capabilities, limitations, and safeguards in light of their particular use cases and requirements. +{% data variables.copilot.copilot_kimi_k3 %} is designed for long-context, multi-step coding and agentic workflows. Fine-tuned model variants may be included as part of the {% data variables.copilot.copilot_kimi_k3 %} ({% data variables.product.github %}) offering on individual plans only. Fine-tuned variants are not included for {% data variables.copilot.copilot_business_short %} or {% data variables.copilot.copilot_enterprise_short %} plans. In pre-release testing, the model exhibited elevated risk on certain higher-risk prompts and was less consistent than some other models in refusing requests involving sensitive topics. These behaviors may reflect differences in the model's safety post-training and alignment. We have deployed additional safeguards in {% data variables.product.prodname_copilot %} to help mitigate the identified risks. As with any model, enterprises should evaluate model capabilities, limitations, and safeguards in light of their particular use cases and requirements. ## Next steps diff --git a/content/copilot/reference/copilot-cli-reference/cli-command-reference.md b/content/copilot/reference/copilot-cli-reference/cli-command-reference.md index 6607071e68b7..d16c02a16bdf 100644 --- a/content/copilot/reference/copilot-cli-reference/cli-command-reference.md +++ b/content/copilot/reference/copilot-cli-reference/cli-command-reference.md @@ -415,7 +415,7 @@ These are the slash commands you can use from within an interactive CLI session. | `/after [DELAY PROMPT]`, `/after` | Schedule a non-recurring prompt, skill, or schedulable slash command for the current session (for example, `/after 30m remind me the time` or `/after 1h /chronicle standup`). With no arguments the schedule manager is displayed. {% data reusables.copilot.experimental %} | | `/agent` | Browse and select from available agents (if any). See [AUTOTITLE](/copilot/concepts/agents/copilot-cli/about-custom-agents). | | `/app` | Open the current session in the {% data variables.copilot.github_copilot_app %} (requires version 1.1.3 or later), or show the download URL if the app is not installed. | -| `/ask QUESTION` | Ask a quick side question without adding to the conversation history. | +| `/ask QUESTION`, `/btw QUESTION` | Ask a quick side question without adding to the conversation history. See [AUTOTITLE](/copilot/how-tos/copilot-cli/use-copilot-cli/ask-a-side-question). | | `/allow-all [off\|auto\|show]`, `/yolo [off\|auto\|show]` | Enable all permissions (tools, paths, and URLs). This is an alias for `/permissions allow-all`; see the `/permissions` row for the canonical command and its subcommands. | | `/autopilot [OBJECTIVE]`, `/goal [OBJECTIVE]` | Start or refocus autopilot mode, optionally with an explicit objective (for example, `/goal Refactor the auth module`). Without an objective, autopilot infers intent from context, and the status panel shows your last prompt as the inferred objective. You can cap AI-credit spend for the objective by using `--max-ai-credits N` (for example, `/goal Refactor the auth module --max-ai-credits 5`). When the cap is reached, autopilot pauses and opens a panel reporting credits used against the cap. Enter a new amount to resume with a fresh credit window, or dismiss the panel to stay paused. You can also resume a paused objective yourself, without the panel, by running the option on its own with no objective text—for example, `/goal --max-ai-credits 5`. This is the same action the panel performs: it opens a fresh window of the credits you specify (the full new cap, not an increment) and continues the objective. `/goal on` and `/goal off` toggle autopilot mode without setting an objective and don't accept `--max-ai-credits`. An active goal renders as a pinned panel above the composer, showing the objective, credits used, and todo progress. The panel auto-collapses to a single identity row on short terminals (below 30 rows) and expands above that threshold; press Ctrl+X then `g` to override the automatic sizing by hand. | | `/changelog [summarize] [VERSION\|last N\|since VERSION]`, `/release-notes [summarize] [VERSION\|last N\|since VERSION]` | Display the CLI changelog. Optionally specify a version, a count of recent releases, or a starting version. Add the keyword `summarize` for an AI-generated summary. | diff --git a/src/cli-docs-auto-maintenance/state/copilot-cli/automation-and-ci.json b/src/cli-docs-auto-maintenance/state/copilot-cli/automation-and-ci.json new file mode 100644 index 000000000000..06b3c4850c81 --- /dev/null +++ b/src/cli-docs-auto-maintenance/state/copilot-cli/automation-and-ci.json @@ -0,0 +1,13 @@ +{ + "name": "Automation and CI", + "sha": "7b8276b2bcaafc444a3dcf482a033352ebb3faa1", + "articles": [ + "content/copilot/concepts/agents/copilot-cli/copilot-cli-in-github-actions.md", + "content/copilot/how-tos/copilot-cli/automate-copilot-cli/automate-with-actions.md", + "content/copilot/how-tos/copilot-cli/automate-copilot-cli/index.md", + "content/copilot/how-tos/copilot-cli/automate-copilot-cli/quickstart.md", + "content/copilot/how-tos/copilot-cli/automate-copilot-cli/run-cli-programmatically.md", + "content/copilot/how-tos/copilot-cli/automate-copilot-cli/schedule-prompts.md", + "content/copilot/how-tos/copilot-cli/use-copilot-cli-in-actions.md" + ] +} diff --git a/src/cli-docs-auto-maintenance/state/copilot-cli/integrations-and-remote-control.json b/src/cli-docs-auto-maintenance/state/copilot-cli/integrations-and-remote-control.json new file mode 100644 index 000000000000..4eceb5f493f7 --- /dev/null +++ b/src/cli-docs-auto-maintenance/state/copilot-cli/integrations-and-remote-control.json @@ -0,0 +1,88 @@ +{ + "name": "Integrations and remote control", + "sha": "7b8276b2bcaafc444a3dcf482a033352ebb3faa1", + "articles": [ + "content/copilot/concepts/agents/copilot-cli/about-remote-control.md", + "content/copilot/concepts/agents/copilot-cli/chronicle.md", + "content/copilot/concepts/agents/copilot-cli/lsp-servers.md", + "content/copilot/how-tos/copilot-cli/set-up-copilot-cli/add-lsp-servers.md", + "content/copilot/how-tos/copilot-cli/use-copilot-cli/browse-issues-prs-gists.md", + "content/copilot/how-tos/copilot-cli/use-copilot-cli/chronicle.md", + "content/copilot/how-tos/copilot-cli/use-copilot-cli/connecting-vs-code.md", + "content/copilot/how-tos/copilot-cli/use-copilot-cli/delegate-tasks-to-cca.md", + "content/copilot/how-tos/copilot-cli/use-copilot-cli/manage-pull-requests.md", + "content/copilot/how-tos/copilot-cli/use-copilot-cli/steer-remotely.md", + "content/copilot/how-tos/copilot-cli/use-copilot-cli/voice-input.md" + ], + "proposed": [ + { + "article": "content/copilot/how-tos/copilot-cli/use-copilot-cli/browse-issues-prs-gists.md", + "text": "* Press / (on the **Issues** and **Pull requests** tabs) to filter the list with your own search terms. Type your terms, press Enter to run the search, and Esc to cancel or clear it." + }, + { + "article": "content/copilot/how-tos/copilot-cli/use-copilot-cli/browse-issues-prs-gists.md", + "text": "To run your own search, press /. An inline search box opens where you can type your search terms, then press Enter to run the search." + }, + { + "article": "content/copilot/how-tos/copilot-cli/use-copilot-cli/browse-issues-prs-gists.md", + "text": "Your search terms are added to the qualifiers the tab already applies, so results are always limited to open items in the current repository—and, unless you have pressed a, to items that involve you. Enter plain search terms rath" + }, + { + "article": "content/copilot/how-tos/copilot-cli/use-copilot-cli/manage-pull-requests.md", + "text": " /pr automerge Do the same as /pr auto, then merge the pull request once it is green. Find out more No Enter with \"Download default model\" selected to download the default multilingual speech-to-text model." + }, + { + "article": "content/copilot/how-tos/copilot-cli/use-copilot-cli/voice-input.md", + "text": "Alternatively, if you want to use the dedicated English or Spanish model:" + }, + { + "article": "content/copilot/how-tos/copilot-cli/use-copilot-cli/voice-input.md", + "text": "1. In the voice models picker, use the arrow keys to select the model you want, then press Enter to download it." + }, + { + "article": "content/copilot/how-tos/copilot-cli/use-copilot-cli/voice-input.md", + "text": "The default multilingual model handles more than one language, but you can switch to the dedicated English or Spanish model if you prefer. The model you want must be downloaded and activated before you can use it." + }, + { + "article": "content/copilot/how-tos/copilot-cli/use-copilot-cli/voice-input.md", + "text": "1. In the voice models picker, use the arrow keys on your keyboard to select the model you want to use, then press Enter." + } + ], + "rejected": [] +} diff --git a/src/cli-docs-auto-maintenance/state/copilot-cli/setup-and-installation.json b/src/cli-docs-auto-maintenance/state/copilot-cli/setup-and-installation.json new file mode 100644 index 000000000000..1301d70d57bd --- /dev/null +++ b/src/cli-docs-auto-maintenance/state/copilot-cli/setup-and-installation.json @@ -0,0 +1,106 @@ +{ + "name": "Setup and installation", + "sha": "8f269b4e7f4cd58744a6edf8093e55820f6d765c", + "articles": [ + "content/copilot/concepts/agents/copilot-cli/about-copilot-cli.md", + "content/copilot/concepts/agents/copilot-cli/index.md", + "content/copilot/how-tos/copilot-cli/cli-getting-started.md", + "content/copilot/how-tos/copilot-cli/index.md", + "content/copilot/how-tos/copilot-cli/set-up-copilot-cli/authenticate-copilot-cli.md", + "content/copilot/how-tos/copilot-cli/set-up-copilot-cli/configure-copilot-cli.md", + "content/copilot/how-tos/copilot-cli/set-up-copilot-cli/index.md", + "content/copilot/how-tos/copilot-cli/set-up-copilot-cli/install-copilot-cli.md", + "content/copilot/how-tos/copilot-cli/set-up-copilot-cli/troubleshoot-copilot-cli-auth.md" + ], + "proposed": [ + { + "article": "content/copilot/how-tos/copilot-cli/set-up-copilot-cli/authenticate-copilot-cli.md", + "text": "When authentication is required, {% data variables.copilot.copilot_cli_short %} supports several methods. The method you use depends on whether you are working interactively or in an automated environment." + }, + { + "article": "content/copilot/how-tos/copilot-cli/set-up-copilot-cli/authenticate-copilot-cli.md", + "text": "* **OAuth**: The default and recommended method for interactive use. There are two OAuth flows. The browser (web) flow opens your browser to authorize the sign-in and completes it on a local loopback callback. The device code flow displays " + }, + { + "article": "content/copilot/how-tos/copilot-cli/set-up-copilot-cli/authenticate-copilot-cli.md", + "text": "| OAuth token (browser or device flow) | `gho_` | Yes | Default method via `copilot login` |" + }, + { + "article": "content/copilot/how-tos/copilot-cli/set-up-copilot-cli/authenticate-copilot-cli.md", + "text": "> * An environment variable silently overrides a stored OAuth token. If you set `GH_TOKEN` for another tool, the CLI uses that token instead of the OAuth token from `copilot login`. To avoid unexpected behavior, unset environment variables " + }, + { + "article": "content/copilot/how-tos/copilot-cli/set-up-copilot-cli/authenticate-copilot-cli.md", + "text": "OAuth is the default authentication method for interactive use. You can authenticate by running `/login` from {% data variables.copilot.copilot_cli_short %} or `copilot login` from your terminal. Both offer a browser (web) flow and a device" + }, + { + "article": "content/copilot/how-tos/copilot-cli/set-up-copilot-cli/authenticate-copilot-cli.md", + "text": "1. Choose how you want to sign in. The recommended option is listed first, and depends on your environment: the browser flow on a local terminal, or the device code flow in a known remote or headless environment." + }, + { + "article": "content/copilot/how-tos/copilot-cli/set-up-copilot-cli/authenticate-copilot-cli.md", + "text": "How do you want to sign in? 1. Sign in with your browser (recommended) 2. Sign in with a device code" + }, + { + "article": "content/copilot/how-tos/copilot-cli/set-up-copilot-cli/authenticate-copilot-cli.md", + "text": "* **Browser**: {% data variables.copilot.copilot_cli_short %} opens your browser so that you can authorize the sign-in. If your browser does not open automatically, the terminal displays a URL that you can visit instead." + }, + { + "article": "content/copilot/how-tos/copilot-cli/set-up-copilot-cli/authenticate-copilot-cli.md", + "text": "* **Device code**: The CLI displays a one-time user code, and can copy it to your clipboard and open your browser for you." + }, + { + "article": "content/copilot/how-tos/copilot-cli/set-up-copilot-cli/authenticate-copilot-cli.md", + "text": "```text Waiting for authorization... Enter one-time code: 1234-5678 at https://github.com/login/device Press any key to copy to clipboard and open browser... ```" + }, + { + "article": "content/copilot/how-tos/copilot-cli/set-up-copilot-cli/authenticate-copilot-cli.md", + "text": "Navigate to the verification URL at `https://github.com/login/device` if your browser did not open automatically, then paste the one-time code in the field on the page." + }, + { + "article": "content/copilot/how-tos/copilot-cli/set-up-copilot-cli/authenticate-copilot-cli.md", + "text": "On a local desktop, `copilot login` uses the browser flow by default. It opens your browser to authorize the sign-in and captures the result on a local loopback callback." + }, + { + "article": "content/copilot/how-tos/copilot-cli/set-up-copilot-cli/authenticate-copilot-cli.md", + "text": "```text Opening your browser to authenticate... If it doesn't open automatically, visit: URL Waiting for authorization... ```" + }, + { + "article": "content/copilot/how-tos/copilot-cli/set-up-copilot-cli/authenticate-copilot-cli.md", + "text": "Known remote or headless environments (including SSH, {% data variables.product.prodname_github_codespaces %}, dev containers, and CI) use the device code flow instead. The CLI displays a one-time code, and copies it to your clipboard and o" + }, + { + "article": "content/copilot/how-tos/copilot-cli/set-up-copilot-cli/authenticate-copilot-cli.md", + "text": "To authenticate, visit https://github.com/login/device and enter code 1234-5678 Waiting for authorization..." + }, + { + "article": "content/copilot/how-tos/copilot-cli/set-up-copilot-cli/authenticate-copilot-cli.md", + "text": "To force a particular flow, add the `--web-flow` or `--device-code` option." + }, + { + "article": "content/copilot/how-tos/copilot-cli/set-up-copilot-cli/authenticate-copilot-cli.md", + "text": "1. Navigate to the URL displayed in your terminal if your browser did not open automatically. For the device code flow, paste the one-time code in the field on the page." + }, + { + "article": "content/copilot/how-tos/copilot-cli/set-up-copilot-cli/troubleshoot-copilot-cli-auth.md", + "text": "export COPILOT_GITHUB_TOKEN=PERSONAL_ACCESS_TOKEN" + }, + { + "article": "content/copilot/how-tos/copilot-cli/set-up-copilot-cli/troubleshoot-copilot-cli-auth.md", + "text": "A token starting with `ghp_` is rejected. If it is the only credential available, {% data variables.copilot.copilot_cli_short %} refuses to start and displays the following error, naming the environment variable that holds the token." + }, + { + "article": "content/copilot/how-tos/copilot-cli/set-up-copilot-cli/troubleshoot-copilot-cli-auth.md", + "text": " ```text Error: Classic Personal Access Tokens (ghp_) are not supported by Copilot." + }, + { + "article": "content/copilot/how-tos/copilot-cli/set-up-copilot-cli/troubleshoot-copilot-cli-auth.md", + "text": "The GITHUB_TOKEN environment variable contains a classic PAT. Please use a Fine-Grained Personal Access Token or another authentication method." + }, + { + "article": "content/copilot/how-tos/copilot-cli/set-up-copilot-cli/troubleshoot-copilot-cli-auth.md", + "text": "To fix this, you can: • Replace the token in GITHUB_TOKEN with a fine-grained PAT • Unset GITHUB_TOKEN and run 'gh auth login' to authenticate • Unset GITHUB_TOKEN and start 'copilot', then use the '/login' command ```