Usar anexos de conteúdo

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://`.

{
  "action": "created",
  "content_reference": {
    "id": 17,
    "node_id": "MDE2OkNvbnRlbnRSZWZlcmVuY2UxNjA5",
    "reference": "errors.ai"
  },
  "repository": {...},
  "sender": {...},
  "installation": {
    "id": 371641,
    "node_id": "MDIzOkludGVncmF0aW9uSW5zdGFsbGF0aW9uMzcxNjQx"
  }
}

Etapa 4. O aplicativo usa o content_reference id 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.

application/vnd.github.corsair-preview+json

O parâmetro do texto pode conter markdown:

<pre><code class="hljs language-shell">curl -X POST \
  https://api.github.com/content_references/1512/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()"
}'</code></pre>

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:

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.

application/vnd.github.corsair-preview+json

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" "https://api.github.com/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
    # O conjunto de permissões necessárias para o aplicativo GitHub. 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: `/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:

   

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: