Copilot Spaces

Copilot Spaces

Use Copilot Spaces to bring curated, project-specific context into conversations. A Space is a shared collection of repositories, files, documentation, and instructions that grounds Copilot responses in your team's actual code and knowledge.

Available Tools

MCP Tools (Read-only)

REST API via gh api (Full CRUD)

The Spaces REST API supports creating, updating, deleting spaces, and managing collaborators. The MCP server only exposes read operations, so use gh api for writes.

User Spaces:

Organization Spaces: Same pattern under /orgs/{org}/copilot-spaces/...

Collaborators: Add, list, update, and remove collaborators at .../collaborators

Scope requirements: PAT needs read:user for reads, user for writes. Add with gh auth refresh -h github.com -s user.

Note: This API is functional but not yet in the public REST API docs. It may require the copilot_spaces_api feature flag.

When to Use Spaces

• User mentions "Copilot space" or asks to "load a space"
• User wants answers grounded in specific project docs, code, or standards
• User asks "what spaces are available?" or "find a space for X"
• User needs onboarding context, architecture docs, or team-specific guidance
• User wants to follow a structured workflow defined in a Space (templates, checklists, multi-step processes)

Workflow

1. Discover Spaces

When a user asks what spaces are available or you need to find the right space:

Call mcp__github__list_copilot_spaces

This returns all spaces the user can access, each with a name and owner_login. Present relevant matches to the user.

To filter for a specific user's spaces, match owner_login against the username (e.g., "show me my spaces").

2. Load a Space

When a user names a specific space or you've identified the right one:

Call mcp__github__get_copilot_space with:
  owner: "org-or-user"    (the owner_login from the list)
  name: "Space Name"      (exact space name, case-sensitive)

This returns the space's full content: attached documentation, code context, custom instructions, and any other curated materials. Use this context to inform your responses.

3. Follow the Breadcrumbs

Space content often references external resources: GitHub issues, dashboards, repos, discussions, or other tools. Proactively fetch these using other MCP tools to gather complete context. For example:

• A space references an initiative tracking issue. Use issue_read to get the latest comments.
• A space links to a project board. Use project tools to check current status.
• A space mentions a repo's masterplan. Use get_file_contents to read it.

4. Answer or Execute

Once loaded, use the space content based on what it contains:

If the space contains reference material (docs, code, standards):

• Answer questions about the project's architecture, patterns, or standards
• Generate code that follows the team's conventions
• Debug issues using project-specific knowledge

If the space contains workflow instructions (templates, step-by-step processes):

• Follow the workflow as defined, step by step
• Gather data from the sources the workflow specifies
• Produce output in the format the workflow defines
• Show progress after each step so the user can steer

5. Manage Spaces (via gh api)

When a user wants to create, update, or delete a space, use gh api. First, find the space number from the list endpoint.

Update a space's instructions:

gh api users/{username}/copilot-spaces/{number} \
  -X PUT \
  -f general_instructions="New instructions here"

Update name, description, or instructions together:

gh api users/{username}/copilot-spaces/{number} \
  -X PUT \
  -f name="Updated Name" \
  -f description="Updated description" \
  -f general_instructions="Updated instructions"

Create a new space:

gh api users/{username}/copilot-spaces \
  -X POST \
  -f name="My New Space" \
  -f general_instructions="Help me with..." \
  -f visibility="private"

Attach resources (replaces entire resource list):

{
  "resources_attributes": [
    { "resource_type": "free_text", "metadata": { "name": "Notes", "text": "Content here" } },
    { "resource_type": "github_issue", "metadata": { "repository_id": 12345, "number": 42 } },
    { "resource_type": "github_file", "metadata": { "repository_id": 12345, "file_path": "docs/guide.md" } }
  ]
}

Delete a space:

gh api users/{username}/copilot-spaces/{number} -X DELETE

Updatable fields: name, description, general_instructions, icon_type, icon_color, visibility ("private"/"public"), base_role ("no_access"/"reader"), resources_attributes

Examples

Example 1: User Asks for a Space

User: "Load the Accessibility copilot space"

Action:

1. Call mcp__github__get_copilot_space with owner "github", name "Accessibility"
2. Use the returned context to answer questions about accessibility standards, MAS grades, compliance processes, etc.