Skip to content

CONFIGURATION.md

Latest commit

 

History

History
81 lines (52 loc) · 2.54 KB

CONFIGURATION.md

File metadata and controls

81 lines (52 loc) · 2.54 KB
Raw

Configuration

This guide covers the most common configuration tasks after installing GitHub Copilot for Xcode.

Authentication

GitHub Copilot account

  1. Open the GitHub Copilot for Xcode app.
  2. Click Sign in.
  3. Finish the browser-based device authorization flow with the GitHub account that has Copilot access.
  4. Confirm the app shows the signed-in state before opening Xcode workflows that depend on chat, code review, or agent mode.

Sign out

Use the app settings to sign out if you need to switch to a different Copilot-enabled account.

Permissions

Copilot for Xcode works best when these permissions are granted:

  • Background for the host app and communication bridge
  • Accessibility for realtime editor context and accepting suggestions
  • Xcode Source Editor Extension for the Editor menu integration
  • Files & Folders for workspace-aware chat and agent operations
  • Screen Recording only when using Copilot Vision

See TROUBLESHOOTING.md for exact macOS settings locations.

Model configuration

GitHub-hosted models

After signing in, open Chat or Agent Mode and use the model picker to select the available Copilot-backed models for your account.

Bring Your Own Key (BYOK)

Use BYOK when you want to supply provider-specific credentials instead of relying only on your Copilot account.

Supported providers are documented in Docs/BYOK.md, including:

  • Anthropic
  • Azure
  • Gemini
  • Groq
  • OpenAI
  • OpenRouter

General flow:

  1. Open Chat.
  2. Choose Manage Models from the model picker.
  3. Add the provider credentials required by your model vendor.
  4. Enable the saved models you want to expose in Xcode.

Never commit provider secrets, API keys, or tokens into project files.

Workspace-aware features

For best results with chat, code review, and agent mode:

  • Open the .xcodeproj, .xcworkspace, or playground before starting a task.
  • Allow file-system access if macOS prompts you.
  • Keep the relevant files open in Xcode so Copilot can use editor context.

Prompt and instruction files

You can further customize Copilot behavior with:

Error recovery

If configuration stops working:

  1. Check whether the app is still signed in.
  2. Verify the required permissions are still enabled.
  3. Restart Xcode after changing extension or accessibility settings.
  4. Reopen the Copilot app and retry the action.
  5. Collect logs from ~/Library/Logs/GitHubCopilot/ if the issue persists.