Integrando propriedades personalizadas a um sistema externo

Você pode gravar automaticamente metadados de um sistema externo, como um catálogo de software ou um portal interno para desenvolvedores, nas propriedades personalizadas do repositório no GitHub. Isso torna o sistema externo a fonte da verdade para essas propriedades e ajuda você a manter o contexto de negócios, como propriedade, camada de serviço ou status de conformidade atualizado em seus repositórios. As propriedades externas podem ser usadas nos mesmos locais que as propriedades personalizadas gerenciadas em GitHub.

Para configurar essa automação, você instalará um GitHub App que chama os endpoints da API de GitHub para propriedades externas com dados do sistema externo.

• Nossa parceira de integração Port desenvolveu uma integração para propriedades personalizadas externas. Para ver todas as etapas necessárias para sincronizar metadados do Port, consulte Sincronizar propriedades do Port com GitHub propriedades personalizadas externas na documentação do Port. GitHub trabalhará para adicionar mais provedores no futuro.
• Se sua organização usa outro sistema externo ou se você é representante de um sistema externo e deseja criar uma integração com GitHub, será necessário criar sua própria GitHub App e automação. Continue lendo este guia.

Pré-requisitos

Esse processo pode exigir várias pessoas diferentes. Você precisará de:

• Alguém para configurar o GitHub App, em sua conta pessoal ou em uma conta de organização ou corporativa da qual seja proprietário(a)
• Um ou mais proprietários de organização em GitHub para instalar o aplicativo em cada organização onde ele for necessário e, possivelmente, registrar um nome de exibição para o aplicativo

Fora do escopo deste guia, você também precisará de alguém que possa criar e executar a automação, com acesso apropriado ao sistema externo e ao servidor em que a automação será executada.

1. Escolha um nome de exibição

Cada chave externa de propriedade personalizada em sua organização receberá como prefixo um nome de exibição. Por exemplo: port.environment. Isso atua como um namespace e ajuda a evitar conflitos com propriedades personalizadas gerenciadas em GitHub ou em outros provedores externos.

Cada nome de exibição está vinculado a uma única instalação do GitHub App dentro da organização. Antes de um aplicativo poder gravar propriedades personalizadas em GitHub, você deve registrar a instalação do aplicativo com um nome para exibição. Esse é um processo único que pode ser executado pelo próprio aplicativo ou por um administrador da organização. Uma instalação de aplicativo só pode ser registrada uma vez e seu nome de exibição não pode ser alterado mais tarde.

Escolha um nome que evitará conflitos e ajudará os usuários a identificar propriedades personalizadas do sistema externo. Se você estiver publicando um aplicativo em nome de um sistema de terceiros, convém responder a conflitos ou permitir que os usuários escolham seu próprio nome de exibição como parte do fluxo de instalação em seu sistema.

O nome de exibição deve ter entre 1 e 15 caracteres e conter apenas letras e números. Para ver todos os requisitos, consulte o endpoint Registrar uma instalação de aplicativo para propriedades externas da API REST.

2. Registrar um GitHub App

GitHub App é a identidade que chamará as APIs para gerenciar propriedades personalizadas externas. Ele também pode monitorar webhooks de eventos em GitHub.

Se você estiver criando um aplicativo para um processo interno, recomendamos criar o aplicativo em uma organização ou conta corporativa. Em seguida, você poderá instalar o aplicativo em quantas organizações precisar. Se você for um representante de um sistema de terceiros, provavelmente publicará o aplicativo para GitHub Marketplace que outras empresas possam instalá-lo.

Para obter instruções, consulte Registrando um aplicativo GitHub.

Selecionando permissões

Em Permissões da organização, habilite a permissão Propriedades personalizadas externas para repositórios para que o aplicativo possa gravar dados na API de propriedades externas. O nível de acesso necessário depende do que o aplicativo precisa fazer:

• Escolha acesso de administrador se o aplicativo registrar seu próprio nome de exibição usando seu token de acesso de instalação. Esse é um bom modelo para um aplicativo de autoatendimento que será instalado em muitas organizações.
• Escolha acesso de leitura e gravação se o aplicativo precisar gravar apenas propriedades personalizadas em GitHub. Um administrador da organização precisará registrar o nome de exibição para sua instalação.

O acesso somente leitura não é uma opção para essa tarefa. Um aplicativo com esse nível de acesso só poderá ler suas próprias definições de propriedade personalizada externa.

Se você quiser assinar eventos de webhook, talvez seja necessário habilitar permissões adicionais.

Para obter mais informações, consulte Permissões necessárias para aplicativos GitHub.

Selecionar webhooks

Você pode habilitar webhooks para assinar eventos em GitHub que devem disparar a transferência de dados do seu sistema externo.

Por exemplo:

• Quando um aplicativo é instalado em uma organização (o installation evento com a ação created ), isso pode disparar a primeira sincronização do sistema externo para os repositórios da organização. Esse evento é enviado a todos GitHub Apps por padrão.
• Quando um novo repositório é criado na organização (o repository evento com a ação created ), o repositório pode ser preenchido automaticamente com metadados. Esse evento requer acesso de leitura à permissão do repositório de metadados .

Os webhooks não serão necessários se você preferir que a automação simplesmente seja executada em um agendamento.

Para obter mais informações, consulte Usando webhooks com aplicativos GitHub.

Selecionando o escopo da instalação

Em Onde esse aplicativo GitHub pode ser instalado?, verifique se seu aplicativo pode ser instalado em todas as organizações em que ele é necessário.

3. Criar a automação

A automação pode ser executada de acordo com uma programação ou detectar eventos. O webhook selecionado para o aplicativo determina quais eventos GitHub são encaminhados para a URL do webhook. Você também pode querer responder a eventos no sistema de terceiros, como alterações nos valores de metadados.

Na automação, o GitHub App deve obter um token de acesso à instalação e usar o token para enviar dados do sistema externo para os pontos de extremidade da API de propriedades externas do GitHub. Consulte Como autenticar como uma instalação de Aplicativo GitHub.

Consulte os endpoints a seguir da API REST. Você encontrará informações sobre os limites de tamanho da solicitação e os códigos de erro que sua automação deve considerar.

• Registrar uma instalação de aplicativo para propriedades personalizadas externas (o aplicativo deve registrar seu nome de exibição antes de atualizar as propriedades, a menos que um administrador da organização faça isso)
• Obter instalações de aplicativo registradas para propriedades personalizadas externas
• Obter todas as propriedades personalizadas externas para uma GitHub App instalação em uma organização
• Criar ou atualizar valores de propriedade personalizada externa para repositórios da organização
• Criar ou atualizar valores de propriedade personalizada externa para uma propriedade entre repositórios da organização
• Remover todos os valores de propriedade personalizada externa para uma propriedade em todos os repositórios da organização

4. Instalar o aplicativo

Instale o GitHub App nas organizações onde isso for necessário, autorizando as permissões de que ele precisa. Consulte Instalando seu próprio aplicativo GitHub.

Como a permissão de propriedades personalizadas externas tem escopo de organização, o aplicativo será instalado com acesso a todos os repositórios por padrão. Você não verá uma opção para selecionar repositórios individuais, a menos que o aplicativo também tenha permissões no nível do repositório.

Se o aplicativo não registrar automaticamente um nome de exibição ou você não puder autorizar o acesso de Administrador , um administrador da organização deverá registrar o nome de exibição para a instalação. Isso pode ser um proprietário da organização ou alguém com a organization_external_properties_for_repos:admin permissão refinada. Consulte Registrar uma instalação de aplicativo para propriedades personalizadas externas.

5. Validar a transferência de dados

Depois que a automação for executada, valide se as propriedades externas estão sendo sincronizadas com os repositórios da organização. Você deve ser capaz de vê-los nas configurações de propriedade personalizada para sua organização ou seus repositórios. As chaves de propriedade serão prefixadas com o nome de exibição externo e os valores serão indicados com um ícone. Consulte Como gerenciar propriedades personalizadas para repositórios na sua organização.

Os valores de propriedades externas também são retornados juntamente com as propriedades personalizadas tradicionais no endpoint da API REST Get all custom property values for a repository. No entanto, /schema endpoints para propriedades personalizadas, como "Obter todas as propriedades personalizadas de uma organização", não retornam propriedades externas.

Os usuários não poderão editar essas propriedades GitHub, mas poderão usá-las em qualquer lugar em que usarem propriedades personalizadas tradicionais.

6. Manter a integração

Mantenha a automação em execução e o aplicativo instalado para continuar sincronizando dados do sistema externo. Se você desinstalar o GitHub App de uma organização, a instalação e o nome de exibição serão cancelados, e todas as propriedades externas que o aplicativo criou serão removidas.

Preste atenção ao número de propriedades definidas na organização. Cada organização pode ter até 100 definições de propriedade. As propriedades personalizadas externas e as propriedades personalizadas padrão são contabilizadas nesse limite.