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:

demo screenshot

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: content references permission Make sure to select the Content reference event: 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:

demo screenshot

Getting started

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

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!

Postponing stricter validation

Recently we announced plans for stricter validation in our REST API and have been monitoring the effect these changes would have on integrators. After careful consideration, we've decided to not rollout stricter validation at this time.

The preview header introduced as part of this change will remain intact. You can continue to use stricter validation by passing the following header:

application/vnd.github.speedy-preview+json

We still believe that stricter validation would have a positive impact on our REST API overall and are looking for alternative ways to introduce it. Stay tuned for future updates.

If you have any questions, please reach out!

GitHub Services Brownout Updates and Timeline

On October 1st, we announced that we were going to do a week-long brownout of GitHub Services-based webhooks this week. During this time no GitHub Services payloads would have been delivered. The motivation behind the brownout is to allow our users and integrators to see the places that GitHub Services are still being used and begin working towards migrating away from GitHub Services. After a lot of thought and discussion, we've decided that a week-long brownout at this time would be too disruptive for everyone. Instead, we are going to do a gradual increase in brownouts until the final blackout date of January 31st, 2019 (please see our deprecation timeline for more information on that).

The following is the updated timeline for GitHub Services brownouts:

  • November 7th, 2018: We will suspend GitHub Services deliveries for a few hours throughout the day.
  • December 12th, 2018: GitHub Service deliveries will be suspended for a full 24 hours
  • January 7th, 2019: GitHub Services will be suspended for a full 7 days. Regular deliveries will resume January 14th, 2019.

We will make sure to post a status on our status page at the start and end of each of these brownouts.

Note: If this change affects you, please see our guide to Replacing GitHub Services with webhooks.

Please contact us if you have any questions!

Improved Experience for Marketplace Pending Order Changes

Today we are announcing updates to Marketplace-related webhooks and REST API's that will make handling orders with pending changes easier.

New webhooks

Integrators can now receive hooks when someone submits a plan change that won't be processed until the end of their billing cycle. Learn more here.

Updated API's

The same information can now also be fetched from the REST API.

Learn more about fetching details about a single account or for fetching all accounts on a given plan.

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

Webhook Log Retention Limited to 30 Days

In an effort to provide a more powerful and stable webhook log experience, we are going to begin limiting the webhook log retention to 30 days.

The webhook logs are viewable only from the organization or repository settings UI. We currently allow users to page through webhook logs until the they reach the first delivery for that hook regardless of how old the delivery is. However, as of Friday, November 2nd, users will only be able to page back through 30 days of webhook delivery logs.

Note: This update does not affect GitHub Enterprise. The webhook log retention period on GitHub Enterprise will continue to be 8 days.

Please contact us if you have any questions!

Preview more complete workflows for Pull Requests in GraphQL

To go with our recent issues preview, we're releasing a more exhaustive Pull Request API in GraphQL to enable you to close or merge pull requests.

For a more complete list of new objects and mutations made available during this preview, please refer to the GraphQL docs.

To access this new API during the preview period, you must provide a custom media type in the Accept header:

  application/vnd.github.ocelot-preview

Note: GraphQL APIs under preview cannot be accessed via the GraphQL Explorer at this time.

During the preview period, we may change aspects of these APIs based on developer feedback. If we do, we will announce the changes here on the developer blog, but we will not provide any advance notice.

If you have any questions or feedback of other interactions you might like for issues, please let us know!

Introducing the GitHub API Development and Support Forum

For the past two years, we’ve run a special community forum at https://platform.github.community. This forum was designed to elicit feedback on newer API releases, specifically the GraphQL API and GitHub Apps, and it gave our ecosystem engineers direct access to your technical questions and feedback. As expected, your questions and needs have expanded as GraphQL and GitHub Apps have matured.

So today we're excited to announce that we are merging the GitHub Platform Forum into the GitHub Community Forum and expanding the focus to include all Platform features beyond the GraphQL API and GitHub Apps.

Why? We want everyone to benefit from each other's questions, workflows, and experiences with our Platform. We're confident this new forum's expanded focus and centralized location will help us and our growing community address issues quickly and efficiently. This forum is a place where you can ask technical questions about any aspect of the GitHub Platform, share your projects and ideas, and suggest new features and directions for the future.

As a contributor to the old GitHub Platform Forum, what does this mean for you? Mostly, it means learning a new URL. Your account will carry over. However, for now we will not port over existing content. We will lock the Platform Forum to read-only mode, so you can still read existing content for now but will not be able to post there.

We hope you’ll join us and all the other developers hanging out at the new GitHub API Development and Support Forum. If you have any questions, please let us know on the forum!

Improvements to the Deployment Statuses API

We are announcing a preview period with expanded functionality for the Deployments API.

Set deployment status environment

You can now update the environment of a deployment by passing the environment parameter when creating a deployment status. If an environment is not passed, the current deployment environment is used. The default environment is production.

New deployment status states

The state parameter now accepts two new states for a deployment status: in_progress and queued.

Auto-inactive status now available in production

The auto_inactive parameter allows you to automatically add a new inactive status to all prior non-transient deployments with the same repository and environment name as the created status's deployment. An inactive status is only added to deployments that have a success state. By default, auto_inactive is enabled.

Before this preview period, auto_inactive was not available in the production environment.

Preview period

To access this expanded functionality during the preview period, you must provide a custom media type in the Accept header:

application/vnd.github.flash-preview+json

During the preview period, we may change aspects of these API parameters based on developer feedback. If we do, we will announce the changes here on the developer blog, but we will not provide any advance notice.

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

Additional endpoints available for GitHub Apps

Today we are announcing the expanded availability of REST API endpoints for GitHub Apps, as we've enabled another batch of endpoints. For a complete list of endpoints enabled for GitHub Apps, see "Available endpoints".

Recently enabled server-to-server and user-to-server endpoints are available in these APIs:

Additional recently enabled user-to-server endpoints are available in these APIs:

How can I try it?

To access this functionality, you’ll need to provide the following custom media type in the Accept header:

application/vnd.github.machine-man-preview+json

What about other endpoints?

For now, this will be the last set of endpoints we enable for the REST API. If you have specific requests or feedback, come chat with us in the Platform forum.

Denying new GitHub Services

As we announced back in April, starting today, additional GitHub Services cannot be added to any repository on GitHub.com, via the UI or API. You can continue to edit or delete existing GitHub Services. For more information, see "Replacing GitHub Services."

Ensure that your repositories use newer APIs available for handling events according to the following changes that will take place:

  • Currently, the "Create a hook" endpoint accepts a required argument called name, which can be set to web for webhooks, or the name of any valid service. Starting today, this endpoint does not require name to be provided; if it is, it will only accept web as a valid value.

    Once stricter API validation is enforced on November 1st, name will be no longer be necessary as a required argument, and requests sending this value will be rejected.

  • For the week of November 5th, 2018, there will be a week-long brownout for GitHub Services. Any GitHub Service installed on a repository will not receive any payloads. Normal GitHub Services operations will resume at the conclusion of the brownout.

  • On January 31, 2019, we will permanently stop delivering all installed services' events on GitHub.com.

Please contact us if you have any questions!