Replacing GitHub Services
We have deprecated GitHub Services in favor of integrating with webhooks. This guide helps you transition to webhooks from GitHub Services. For more information on this announcement, see the blog post.
- Deprecation timeline
- GitHub Services background
- GitHub Services vs. webhooks
- Replacing Services with webhooks
- Supporting GitHub Enterprise Server
- Migrating with our help
- October 1, 2018: GitHub discontinued allowing users to install services. We removed GitHub Services from the GitHub.com user interface.
- January 31, 2019: GitHub will stop delivering installed services' events on GitHub.com.
GitHub Services background
GitHub Services (sometimes referred to as Service Hooks) is the legacy method of integrating where GitHub hosted a portion of our integrator’s services via the
github-services repository. Actions performed on GitHub trigger these services, and you can use these services to trigger actions outside of GitHub.
GitHub Services vs. webhooks
The key differences between GitHub Services and webhooks:
- Configuration: GitHub Services have service-specific configuration options, while webhooks are simply configured by specifying a URL and a set of events.
- Custom logic: GitHub Services can have custom logic to respond with multiple actions as part of processing a single event, while webhooks have no custom logic.
- Types of requests: GitHub Services can make HTTP and non-HTTP requests, while webhooks can make HTTP requests only.
Replacing Services with webhooks
To replace GitHub Services with Webhooks:
Identify the relevant webhook events you’ll need to subscribe to from this list.
Change your configuration depending on how you currently use GitHub Services:
- GitHub Apps: Update your app's permissions and subscribed events to configure your app to receive the relevant webhook events.
OAuth Apps: Request either the
org_hookscope(s) to manage the relevant events on behalf of users.
- GitHub Service providers: Request that users manually configure a webhook with the relevant events sent to you, or take this opportunity to build an app to manage this functionality. For more information, see "About apps."
Move additional configuration from outside of GitHub. Some GitHub Services require additional, custom configuration on the configuration page within GitHub. If your service does this, you will need to move this functionality into your application or rely on GitHub or OAuth Apps where applicable.
Supporting GitHub Enterprise Server
- GitHub Enterprise Server 2.17: GitHub Enterprise Server release 2.17 and higher will discontinue allowing admins to install services.
- GitHub Enterprise Server 2.20: GitHub Enterprise Server release 2.20 and higher will stop delivering all installed services' events.
The GitHub Enterprise Server 2.17 release will be the first release that does not allow admins to install GitHub Services. We will only support existing GitHub Services until the GitHub Enterprise Server 2.20 release. We will also accept any critical patches for your GitHub Service running on GitHub Enterprise Server until October 1, 2019.
Migrating with our help
If you're an integrator whose product is impacted by the deprecation of these services, and you are looking to provide continuity of service to our shared customers, you may contact the Partner Engineering team with any questions or for help with your migration. As a high-level guide, the process of migration will typically involve:
- Identifying how and where your product is using GitHub Services.
- Identifying the corresponding webhook events you need to configure in order to move to plain webhooks.
- Implementing the design using either OAuth Apps or GitHub Apps. GitHub Apps are preferred, for the reasons noted here.
All other users
Please contact us if you have any questions!