Importar e sincronizar plugins do GitHub

Você pode importar plugins do GitHub para o seu espaço de trabalho e mantê-los atualizados à medida que o repositório muda. Um marketplace é um arquivo JSON que lista os plugins a importar.

Antes de começar

Você precisa ser administrador do espaço de trabalho. Use uma conta do GitHub com acesso de leitura ao repositório do marketplace e a todos os repositórios que ele referencia. Há suporte a repositórios públicos e privados do GitHub. Antes de importar, obtenha as aprovações de acesso exigidas pela sua organização no GitHub.

Revise o repositório antes de importá-lo. Estas configurações padrão afetam o que os membros podem usar:

• Os novos plugins ficam com o status Disponível para instalação. Se o plugin exigir autenticação, os membros deverão se autenticar ao instalá-lo.
• A importação processa todas as entradas válidas. A sincronização automática dos novos marketplaces ocorre todos os dias e adiciona os novos plugins do repositório.

Este guia explica como importar plugins para um espaço de trabalho. Para clientes locais, consulte Configurar marketplaces de plugins e opções padrão para saber como definir essas opções na nuvem ou no arquivo config.toml do sistema. Para um projeto específico, consulte Ativar ou desativar um plugin em um repositório.

Configurar a sincronização de um marketplace

1. Abra Administração > Plug-ins e selecione Adicionar > Importar marketplace.
2. Em Origem, insira a URL do repositório, como https://github.com/example/team-plugins. Use apenas a URL do repositório. Não use a URL de uma branch ou pasta.
3. Se o marketplace estiver em um subdiretório, informe esse diretório em Caminho. Por exemplo, use team-tools para team-tools/.agents/plugins/marketplace.json. Se o marketplace estiver na raiz do repositório, deixe Caminho em branco. Não inclua o nome do arquivo de manifesto.
4. Se quiser, preencha o campo Branch, tag ou commit. Deixe-o em branco para usar a branch padrão do repositório. Com uma branch, você pode receber atualizações futuras. Ao especificar um commit, você mantém a versão selecionada.
5. Selecione Importar marketplace e autorize o acesso ao GitHub quando solicitado. A importação inicial pode levar até uma hora para marketplaces muito grandes. As sincronizações diárias seguintes costumam levar alguns minutos.
6. Confira os Resultados da importação e abra cada plugin importado para configurar a política de instalação e os aplicativos necessários.

Formatos compatíveis

O diretório selecionado deve conter um dos seguintes arquivos:

As entradas de um marketplace podem referenciar plugins nativos com .codex-plugin/plugin.json, plugins compatíveis com o Claude, pacotes Agent Plugins 1.0 ou pacotes de habilidades compatíveis.

Em um marketplace do Codex, use caminhos locais para os plugins que estão no mesmo repositório:

{
  "name": "team-plugins",
  "interface": {
    "displayName": "Team plugins"
  },
  "plugins": [
    {
      "name": "team-tools",
      "source": {
        "source": "local",
        "path": "./plugins/team-tools"
      }
    }
  ]
}

O caminho é relativo à raiz selecionada para o marketplace, e não a .agents/plugins/.

Em um marketplace compatível com o Claude, você pode especificar o caminho de cada plugin local como uma string:

{
  "name": "team-plugins",
  "plugins": [
    {
      "name": "team-tools",
      "source": "./plugins/team-tools"
    }
  ]
}

As entradas de um marketplace do Codex também aceitam source: "url" para um plugin na raiz de um repositório do GitHub e source: "git-subdir" para um plugin em um subdiretório de um repositório do GitHub. Por exemplo:

{
  "name": "team-tools",
  "source": {
    "source": "git-subdir",
    "url": "https://github.com/example/team-tools.git",
    "path": "./plugins/team-tools",
    "ref": "main"
  }
}

Em origens Git, você pode especificar uma ref ou o sha completo de um commit, com 40 caracteres. A conta do GitHub usada para autorizar o acesso precisa ter acesso de leitura a todos os repositórios referenciados. No momento, a importação para o espaço de trabalho só aceita repositórios do GitHub.

Configurar o acesso no espaço de trabalho

Configure a instalação e a autenticação de cada plugin no espaço de trabalho. A importação e a sincronização não aplicam essas configurações a partir do repositório. Entre as opções estão AVAILABLE, INSTALLED_BY_DEFAULT, NOT_AVAILABLE, ON_INSTALL e ON_USE. As configurações existentes no espaço de trabalho são mantidas quando você sincroniza uma atualização ou passa a gerenciar um plugin pelo GitHub.

Em Política de instalação, escolha Disponível ou Instalado para cada função elegível. Ative também os aplicativos de que o plugin precisa e verifique se os membros têm acesso ao serviço conectado. A importação de um plugin não concede aos membros acesso aos aplicativos nem conecta suas contas. Consulte Controles de plugins para saber como escolher as configurações de acesso e de ações.

Passar a gerenciar um plugin existente pelo GitHub

Adicione pluginId à entrada do plugin existente no marketplace:

{
  "name": "team-tools",
  "pluginId": "plugin_0123456789abcdef0123456789abcdef",
  "source": {
    "source": "local",
    "path": "./plugins/team-tools"
  }
}

Abra o plugin em Administração > Plug-ins e copie o ID que aparece depois de /plugins/ na URL. Coloque pluginId no mesmo nível de name e source na entrada do marketplace. O plugin existente precisa estar no mesmo espaço de trabalho, e o valor de name na entrada deve corresponder ao nome desse plugin.

Use esse procedimento para passar a gerenciar pelo GitHub um plugin do espaço de trabalho que ainda não seja gerenciado por lá. O plugin mantém o ID, o compartilhamento e as configurações do espaço de trabalho. As próximas atualizações virão do GitHub. Por isso, você não poderá mais substituir o plugin enviando um arquivo compactado. Esse método não pode ser usado para um plugin já gerenciado por outra origem do GitHub.

Plugins exclusivos para desktop

Plugins marcados como Somente desktop não podem ser executados no ChatGPT na Web. Plugins importados podem receber esse rótulo quando declaram servidores MCP, inclusive servidores com URLs HTTPS remotas. Adicionar uma referência a .app.json, por si só, não remove o rótulo.

Referenciar um aplicativo existente com .app.json

Adicione .app.json à raiz do plugin. O nome do arquivo começa com um ponto. O nome app.json, sem o ponto, não é aceito.

{
  "apps": {
    "team-tools": {
      "id": "asdk_app_example",
      "required": true
    }
  }
}

Substitua asdk_app_example pelo ID do aplicativo existente. Os IDs de aplicativo aceitos começam com asdk_app_, connector_ ou templated_apps_. Use o ID do aplicativo, e não um ID plugin_.... Por exemplo, uma URL de plugin que contém plugin_asdk_app_example representa o aplicativo asdk_app_example.

A chave team-tools dá nome à referência nesse arquivo. Defina required como true quando o plugin depender do aplicativo. Você pode adicionar mais entradas para referenciar outros aplicativos existentes.

Para um plugin nativo, defina apps como ./.app.json em .codex-plugin/plugin.json. Este é o manifesto completo do exemplo:

{
  "name": "team-tools",
  "version": "1.0.0",
  "description": "Use the team's approved tools.",
  "author": {
    "name": "Example team"
  },
  "apps": "./.app.json",
  "interface": {
    "displayName": "Team tools",
    "shortDescription": "Use approved team tools",
    "longDescription": "Connect to the team's existing app.",
    "developerName": "Example team",
    "category": "Productivity",
    "capabilities": ["Read"]
  }
}

Mantenha os arquivos nesta estrutura:

team-plugins/
├── .agents/plugins/marketplace.json
└── plugins/team-tools/
    ├── .codex-plugin/plugin.json
    └── .app.json

Esse arquivo aponta para um aplicativo existente. Ele não cria um aplicativo nem concede acesso a ninguém. Disponibilize o aplicativo para as funções que precisam dele e peça aos membros que se autentiquem, se necessário. As permissões do aplicativo, as ações permitidas e as regras de acesso ao serviço conectado continuam valendo.

Manter os plugins atualizados

Os novos marketplaces verificam diariamente se há atualizações. Abra Administração > Plug-ins > Marketplaces, selecione o marketplace e escolha Sincronizar agora para solicitar uma atualização sem esperar pela sincronização automática.

A sincronização pode adicionar novos plugins do marketplace e atualizar os existentes. Revise as alterações do repositório antes de fazer o merge, pois a sincronização automática também importa novos plugins.

Após cada sincronização, confira o status e leia o relatório salvo. Mesmo que a sincronização seja concluída, podem ocorrer erros em plugins individuais. Se uma atualização for inválida, o plugin existente mantém a última versão que funcionou. Corrija o problema no GitHub e selecione Sincronizar agora para tentar novamente.

Quando você remove do marketplace a entrada de um plugin, a cópia do plugin permanece no espaço de trabalho com o rótulo Não consta mais na origem. Se você excluir o marketplace no ChatGPT, também excluirá todos os plugins importados desse marketplace.

Reconectar ou alterar o acesso ao GitHub

A sincronização do marketplace usa a conexão com o GitHub do administrador que fez a importação.

Para restabelecer a conexão, primeiro verifique se a conta do GitHub do administrador que fez a importação ainda tem acesso de leitura ao repositório do marketplace e a todos os repositórios que ele referencia. Em seguida, esse administrador deve abrir o plugin do GitHub no ChatGPT e reconectar a conta.

Para transferir a responsabilidade, o novo administrador do espaço de trabalho deve importar o marketplace novamente em Administração > Plug-ins > Adicionar > Importar marketplace. Use os mesmos valores nos campos Origem, Caminho e Branch, tag ou commit. As próximas sincronizações usarão a conexão do novo administrador com o GitHub.

Mantenha o marketplace ao reconectar a conta ou trocar o responsável. Excluí-lo também exclui os plugins importados dele.