Usar anexos de conteúdo

Sobre os anexos de conteúdo

Um Aplicativo do GitHub pode registrar os domínios que vão disparar eventos content_reference. Quando alguém inclui uma URL vinculada a um domínio registrado no corpo ou no comentário de um problema ou de uma solicitação de pull, o aplicativo recebe o webhook content_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 precisa 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 disparam o evento content_reference.

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

• Conceda permissões Read & write ao seu aplicativo nas "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.

Confira "Como criar um Aplicativo do GitHub" ou "Como editar as permissões de um Aplicativo do GitHub" para ver as etapas necessárias para configurar as permissões do Aplicativo do GitHub e as assinaturas de evento.

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 na solicitação de pull, o evento de webhook content_reference e o ponto de extremidade da API REST que você precisa chamar para atualizar o problema ou a solicitação de pull com informações adicionais:

Etapa 1. Configure seu aplicativo usando as diretrizes descritas em Sobre os anexos de conteúdo. Use também o exemplo de Aplicativo do Probot para começar a usar anexos de conteúdo.

Etapa 2. Adicione a URL para o domínio que você registrou em uma solicitação de pull ou em um problema. Você precisa usar uma URL totalmente qualificada que comece com http:// ou https://.

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

{
  "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 id do content_reference e full_name do repository para criar um anexo de conteúdo usando a API REST. Você também precisará da id do installation para se autenticar como uma instalação do Aplicativo do GitHub.

application/vnd.github.corsair-preview+json

O parâmetro body pode conter um 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 como criar um token de instalação, confira "Autenticação como um Aplicativo do GitHub".

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

Usar anexos de conteúdo no GraphQL

Fornecemos a node_id no evento de webhook content_reference para que você possa se referir �  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" "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, confira "Como usar IDs de nó global".

Exemplo de uso de manifestos do Probot e do aplicativo GitHub

Para configurar rapidamente um Aplicativo do GitHub que possa usar a API do Content Attachments, use o Probot. Confira "Como criar Aplicativos do GitHub com base em um manifesto" para saber como o Probot usa os Manifestos de Aplicativo do GitHub.

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

1. Gerar um novo Aplicativo do GitHub.

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

    default_events:
      - content_reference
    # The set of permissions needed by the GitHub App. The format of the object uses
    # the permission name for the key (for example, issues) and the access type for
    # the value (for example, write).
    # 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 tratar os 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 do GitHub localmente. Navegue até http://localhost:3000 e clique no botão Registrar Aplicativo do 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 que você abriu que inclui a URL configurada no arquivo app.yml.

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