Content Attachments API Public Beta

Developers share a lot of links on GitHub. Nearly one-third of comments on issues and pull requests include a link. Hidden behind each of those links is important context that can inform the conversation. Today we’re excited to announce that you can curate and showcase content to help drive those conversations with the Content Attachments API, which is now in public beta.

GitHub Apps now have the ability to listen for links in issues and pull requests and attach content to those links:

Setting up content attachments

Step 1. Create a GitHub App.

Register the domain that your app would like to create content attachments for (errors.ai in this case). Make sure to select Read & write access: Make sure to select the Content reference event:

Step 2. Install your newly created GitHub App on a repository.

API interaction flow

1. Someone posts a link in an issue or pull request on a repository where your app is installed.

2. Your app will receive a content_reference event with action created. The contents of the content_reference and installation hash are important.

   {
     "action": "created",
     "content_reference": {
       "id": 1512,
       "node_id": "MDE2OkNvbnRlbnRSZWZlcmVuY2UxNTEy",
       "reference": "https://errors.ai/my-project/A-1234"
     },
     "repository": {...},
     "sender": {...},
     "installation": {
       "id": 492164,
       "node_id": "MDIzOkludGVncmF0aW9uSW5zdGFsbGF0aW9uNDkyMTY0"
     }
   }
   

3. Using the content_reference id you can now create a content attachment using the API by supplying a title and body in the API call. You'll also need the installation id to authenticate as a GitHub App installation. You can use markdown in the body parameter.

   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] IntegrityError in core/models.py",
       "body": "duplicate key violates unique constraint user_email_uniq\nDETAIL: Key (email)=(hubot@github.com) already exists..."
   }'
   

4. You'll see the new content attachment appear under the link in a pull request or issue comment on GitHub:

Getting started

Try out one of the apps already supporting content attachments or build your own:

• Remix our Glitch blueprint
• Further documentation

Questions

How many domains can an app register?

An app can register up to 5 domains, read more.

What kind of links are GitHub Apps notified of?

For an app to receive a content_reference event, the posted link must be "free standing", so it cannot be part of a markdown link.

If posted, this link will trigger the content_reference event:

https://example.com/test/url

However, this link will not:

[my favorite URL](https://example.com/test/url)

Also, remember, that for an app to receive the content_reference event, it needs to be installed on the repository and have the matching domain registered. So in the above case the app would need to have example.com registered as a content_reference in the app settings.

If you have any questions or feedback, please let us know!