Skip to main content

Esta versão do GitHub Enterprise foi descontinuada em 2022-06-03. Nenhum lançamento de patch será feito, mesmo para questões críticas de segurança. Para obter melhor desempenho, melhorar a segurança e novos recursos, upgrade to the latest version of GitHub Enterprise. Para ajuda com a atualização, contact GitHub Enterprise support.

Usar anexos de conteúdo

Os anexos de conteúdo permitem que um aplicativo GitHub forneça mais informações no GitHub referente � s URLs ligadas a domínios registrados. O GitHub interpreta as informações fornecidas pelo aplicativo sob a URL do texto ou comentário de um problema ou pull request.

Observação: A API do Anexos do conteúdo está atualmente em beta público e disponível apenas para uso com os aplicativos GitHub. Os recursos e requisitos podem mudar a qualquer momento durante este período.

Sobre os anexos de conteúdo

Um aplicativo GitHub pode registrar domínios que ativarão eventos content_reference. Quando alguém inclui uma URL que é ligada a um domínio registrado no texto ou comentário de um problema ou pull request, o aplicativo recebe o webhookcontent_reference. Você pode usar os anexos de conteúdo para fornecer visualmente mais contexto ou dados para a URL adicionada a um problema ou pull request. A URL deve ser uma URL totalmente qualificada, começando com http:// ou https://. As URLs que fazem parte de um link markdown são ignoradas e não ativam o evento content_reference.

Antes de usar a API Anexos do conteúdo, você deverá configurar as referências de conteúdo para o seu aplicativo GitHub:

  • Dê ao seu aplicativo permissões de Leitura & gravação para as "Referências de conteúdo".
  • Registre até 5 domínios válidos e publicamente acessíveis ao configurar a permissão de "Referências de conteúdo". Não use endereços IP ao configurar domínios de referência de conteúdo. Você pode registrar um nome de domínio (exemplo.com) ou um subdomínio (subdomínio.exemplo.com).
  • Assine seu aplicativo no evento "Referência do conteúdo".

Uma vez instalado seu aplicativo em um repositório, Os comentários do problema ou pull request no repositório que contêm URLs para seus domínios registrados gerarão um evento de referência de conteúdo. O aplicativo deve criar um anexo de conteúdo em seis horas após a URL de referência de conteúdo ser postada.

Os anexos de conteúdo não farão a atualização retroativa das URLs. Funciona apenas para as URLs adicionadas a problemas ou pull requests depois que você configurar o aplicativo que usa os requisitos descritos acima e, em seguida, alguém instalar o aplicativo em seu repositório.

Consulte "Criar um aplicativo GitHub" ou"Editar as permissões de um aplicativo GitHub" para as etapas necessárias para configurar as permissões e assinaturas de eventos do aplicativo GitHub.

Implementar o fluxo de anexo de conteúdo

O fluxo de anexo de conteúdo mostra a relação entre a URL no problema ou pull request, o evento do webhook content_reference, de ` e o ponto de extremidade da API REST que você precisa chamar para atualizar o problema ou pull request com informações adicionais:

Etapa 1. Configure seu aplicativo usando as diretrizes definidas em Sobre anexos de conteúdo. Você também pode usar o exemplo do aplicativo Probot para dar os primeiros passos com os anexos de conteúdo.

Etapa 2. Adicione a URL para o domínio que você registrou para um problema ou pull request. Você deve usar uma URL totalmente qualificada que comece com http://` ou `https://`.

URL adicionada a um problema

Etapa 3. Seu aplicativo receberá o content_reference webhook com a ação criada.

{
  "action": "created",
  "content_reference": {
    "id": 17,
    "node_id": "MDE2OkNvbnRlbnRSZWZlcmVuY2UxNjA5",
    "reference": "errors.ai"
  },
  "repository": {
    "full_name": "Codertocat/Hello-World",
  },
  "sender": {...},
  "installation": {
    "id": 371641,
    "node_id": "MDIzOkludGVncmF0aW9uSW5zdGFsbGF0aW9uMzcxNjQx"
  }
}

Etapa 4. O aplicativo usa os campos content_reference id e repositório full_name para Criar um anexo de conteúdo usando a API REST. Você também precisará do id da instalação para efetuar a autenticação como uma instalação do aplicativo GitHub.

Observação: Para acessar a API do Anexos do conteúdo durante o período de pré-visualização, você deve fornecer um tipo de mídia personalizado no cabeçalho Aceitar:

application/vnd.github.corsair-preview+json

Aviso: A API pode mudar sem aviso prévio durante o período de pré-visualização. Os recursos de visualização não são compatíveis com o uso em produção. Em caso de problemas, entre em contato com your site administrator.

O parâmetro do texto pode conter markdown:

curl -X POST \
  http(s)://[hostname]/api/v3/repos/Codertocat/Hello-World/content_references/17/attachments \
  -H 'Accept: application/vnd.github.corsair-preview+json' \
  -H 'Authorization: Bearer $INSTALLATION_TOKEN' \
  -d '{
    "title": "[A-1234] Error found in core/models.py file",
    "body": "You have used an email that already exists for the user_email_uniq field.\n ## DETAILS:\n\nThe (email)=(Octocat@github.com) already exists.\n\n The error was found in core/models.py in get_or_create_user at line 62.\n\n self.save()"
}'

Para obter mais informações sobre a criação de um token de instalação, consulte "Efetuando a autenticação como um aplicativo GitHub".

Etapa 5. Você verá o novo anexo de conteúdo aparecer no link de um pull request ou comentário de um problema:

Conteúdo anexado a uma referência em um problema

Usar anexos de conteúdo no GraphQL

Nós fornecemos o node_id no evento content_reference webhook para que você possa fazer referência �  mutação createContentAttachment na API do GraphQL.

Observação: Para acessar a API do Anexos do conteúdo durante o período de pré-visualização, você deve fornecer um tipo de mídia personalizado no cabeçalho Aceitar:

application/vnd.github.corsair-preview+json

Aviso: A API pode mudar sem aviso prévio durante o período de pré-visualização. Os recursos de visualização não são compatíveis com o uso em produção. Em caso de problemas, entre em contato com your site administrator.

Por exemplo:

mutation {
  createContentAttachment(input: {
    contentReferenceId: "MDE2OkNvbnRlbnRSZWZlcmVuY2UxNjA1",
    title: "[A-1234] Error found in core/models.py file",
    body:"You have used an email that already exists for the user_email_uniq field.\n ## DETAILS:\n\nThe (email)=(Octocat@github.com) already exists.\n\n The error was found in core/models.py in get_or_create_user at line 62.\n\n self.save()"
  }) {
    contentAttachment {
      ... on ContentAttachment {
        id
        title
        body
      }
    }
  }
}

Exemplo de cURL:

curl -X "POST" "http(s)://[hostname]/api/v3/graphql" \
     -H 'Authorization: Bearer $INSTALLATION_TOKEN' \
     -H 'Accept: application/vnd.github.corsair-preview+json' \
     -H 'Content-Type: application/json; charset=utf-8' \
     -d $'{
  "query": "mutation {\\n  createContentAttachment(input:{contentReferenceId: \\"MDE2OkNvbnRlbnRSZWZlcmVuY2UxNjA1\\", title:\\"[A-1234] Error found in core/models.py file\\", body:\\"You have used an email that already exists for the user_email_uniq field.\n ## DETAILS:\n\nThe (email)=(Octocat@github.com) already exists.\n\n The error was found in core/models.py in get_or_create_user at line 62.\n\n\self.save()\\"}) {\\n    contentAttachment {\\n      id,\\n      title,\\n      body\\n    }\\n  }\\n}"
}'

Para obter mais informações sobre node_id, consulte "Usando IDs de nós globais".

Exemplo de uso de manifestos do Probot e do aplicativo GitHub

Para configurar rapidamente um aplicativo GitHub que pode usar a API do Anexos do conteúdo, você pode usar o Probot. Consulte "Criando aplicativos GitHub a partir de um manifesto" para saber como o Probot usa manigestos do aplicativo GitHub.

Para criar um aplicativo Probot, siga as etapas a seguir:

  1. Gerar um novo aplicativo GitHub.

  2. Abra o projeto que você criou e personalize as configurações no arquivo app.yml. Assine o evento content_reference e habilite as permissões de gravação content_reference:

     default_events:
       - content_reference
     # The set of permissions needed by the GitHub App. O formato do objeto usa
     # o nome da permissão para a chave (por exemplo, problemas) e o tipo de acesso para
     # o valor (por exemplo, gravação)
     # Valid values are `read`, `write`, and `none`
     default_permissions:
       content_references: write
    
     content_references:
       - type: domain
         value: errors.ai
       - type: domain
         value: example.org
    
  3. Adicione este código ao arquivo index.js para lidar com eventos content_reference e chamar a API REST:

    module.exports = app => {
      // Your code here
      app.log('Yay, the app was loaded!')
       app.on('content_reference.created', async context => {
        console.log('Content reference created!', context.payload)
         // Call the "Create a content reference" REST endpoint
        await context.github.request({
          method: 'POST',
          headers: { accept: 'application/vnd.github.corsair-preview+json' },
          url: `/repos/${context.payload.repository.full_name}/content_references/${context.payload.content_reference.id}/attachments`,
          // Parameters
          title: '[A-1234] Error found in core/models.py file',
          body: 'You have used an email that already exists for the user_email_uniq field.\n ## DETAILS:\n\nThe (email)=(Octocat@github.com) already exists.\n\n The error was found in core/models.py in get_or_create_user at line 62.\n\nself.save()'
        })
      })
    }
    
  4. Execute o aplicativo GitHub localmente. Acesse http://localhost:3000 e clique no botão Registrar aplicativo GitHub:

    Registrar um aplicativo GitHub do Probot

  5. Instale o aplicativo em um repositório de teste.

  6. Crie um problema no seu repositório de teste.

  7. Adicione um comentário ao problema aberto que inclui a URL que você configurou no arquivo app.yml.

  8. Dê uma olhada no comentário do problema e você verá uma atualização que se parece com isso:

    Conteúdo anexado a uma referência em um problema