CINXE.COM
Git - Scripting GitHub
<!DOCTYPE html> <html lang="en"> <head> <meta charset='utf-8'> <meta content='IE=edge,chrome=1' http-equiv='X-UA-Compatible'> <meta name="viewport" content="width=device-width, initial-scale=1"> <title>Git - Scripting GitHub</title> <link href="/favicon.ico" rel='shortcut icon' type='image/x-icon'> <link rel="stylesheet" href="/application.min.css"> <script src="/js/modernizr.js"></script> <script src="/js/modernize.js"></script> </head> <body id="documentation"> <div class="inner"> <header> <a href="/"><img src="/images/logo@2x.png" width="110" height="46" alt="Git" /></a> <span id="tagline"></span> <script type="text/javascript"> const taglines = [ "fast-version-control", "everything-is-local", "distributed-even-if-your-workflow-isnt", "local-branching-on-the-cheap", "distributed-is-the-new-centralized" ]; var tagline = taglines[Math.floor(Math.random() * taglines.length)]; document.getElementById('tagline').innerHTML = '--' + tagline; </script> <form id="search" action="/search/results"> <input id="search-text" name="search" placeholder="Type / to search entire site…" autocomplete="off" type="text" /> </form> <div id="search-results"></div> </header> </div> <div class="inner"> <div id="content-wrapper"> <div tabindex="1" class="sidebar-btn"></div> <aside class="sidebar" id="sidebar"> <nav> <ul> <li> <a href="/about">About</a> <ul> </ul> </li> <li> <a href="/doc" class="active">Documentation</a> <ul class="expanded"> <li> <a href="/docs">Reference</a> </li> <li> <a href="/book" class="active">Book</a> </li> <li> <a href="/videos">Videos</a> </li> <li> <a href="/doc/ext">External Links</a> </li> </ul> </li> <li> <a href="/downloads">Downloads</a> <ul > <li> <a href="/downloads/guis">GUI Clients</a> </li> <li> <a href="/downloads/logos">Logos</a> </li> </ul> </li> <li> <a href="/community">Community</a> </li> </ul> <hr class="sidebar"> <p> This book is available in <a href="/book/en/v2/GitHub-Scripting-GitHub">English</a>. </p> <p> Full translation available in <table> <tr><td><a href="/book/az/v2/GitHub-GitHub-Skriptl%c9%99m%c9%99">azərbaycan dili</a>,</td></tr> <tr><td><a href="/book/bg/v2/%d0%9d%d0%b0%d1%81%d1%82%d1%80%d0%be%d0%b9%d0%b2%d0%b0%d0%bd%d0%b5-%d0%bd%d0%b0-Git-%d0%9e%d0%b1%d0%be%d0%b1%d1%89%d0%b5%d0%bd%d0%b8%d0%b5">български език</a>,</td></tr> <tr><td><a href="/book/de/v2/GitHub-Skripte-mit-GitHub">Deutsch</a>,</td></tr> <tr><td><a href="/book/es/v2/GitHub-Scripting-en-GitHub">Español</a>,</td></tr> <tr><td><a href="/book/fr/v2/GitHub-%c3%89criture-de-scripts-pour-GitHub">Français</a>,</td></tr> <tr><td><a href="/book/gr">Ελληνικά</a>,</td></tr> <tr><td><a href="/book/ja/v2/GitHub-%e3%82%b9%e3%82%af%e3%83%aa%e3%83%97%e3%83%88%e3%81%ab%e3%82%88%e3%82%8b-GitHub-%e3%81%ae%e6%93%8d%e4%bd%9c">日本語</a>,</td></tr> <tr><td><a href="/book/ko/v2/GitHub-GitHub-%ec%8a%a4%ed%81%ac%eb%a6%bd%ed%8c%85">한국어</a>,</td></tr> <tr><td><a href="/book/nl/v2/GitHub-GitHub-Scripten">Nederlands</a>,</td></tr> <tr><td><a href="/book/ru/v2/GitHub-%d0%a1%d0%be%d0%b7%d0%b4%d0%b0%d0%bd%d0%b8%d0%b5-%d1%81%d1%86%d0%b5%d0%bd%d0%b0%d1%80%d0%b8%d0%b5%d0%b2-GitHub">Русский</a>,</td></tr> <tr><td><a href="/book/sl/v2/GitHub-Skriptni-GitHub">Slovenščina</a>,</td></tr> <tr><td><a href="/book/tl/v2/GitHub-Pag-iiskrip-sa-GitHub">Tagalog</a>,</td></tr> <tr><td><a href="/book/uk/v2/GitHub-%d0%a1%d0%ba%d1%80%d0%b8%d0%bf%d1%82%d1%83%d0%b2%d0%b0%d0%bd%d0%bd%d1%8f-GitHub">Українська</a></td></tr> <tr><td><a href="/book/zh/v2/GitHub-%e8%84%9a%e6%9c%ac-GitHub">简体中文</a>,</td></tr> </table> </p> <p> Partial translations available in <table> <tr><td><a href="/book/cs/v2/GitHub-Scripting-GitHub">Čeština</a>,</td></tr> <tr><td><a href="/book/mk/v2/GitHub-%d0%a3%d0%bf%d1%80%d0%b0%d0%b2%d1%83%d0%b2%d0%b0%d1%9a%d0%b5-%d1%81%d0%be-%d0%be%d1%80%d0%b3%d0%b0%d0%bd%d0%b8%d0%b7%d0%b0%d1%86%d0%b8%d1%98%d0%b0">Македонски</a>,</td></tr> <tr><td><a href="/book/pl/v2/GitHub-Scripting-GitHub">Polski</a>,</td></tr> <tr><td><a href="/book/sr/v2/GitHub-%d0%9f%d0%b8%d1%81%d0%b0%d1%9a%d0%b5-%d1%81%d0%ba%d1%80%d0%b8%d0%bf%d1%82%d0%b8-%d0%b7%d0%b0-GitHub">Српски</a>,</td></tr> <tr><td><a href="/book/uz/v2/GitHub-Scripting-GitHub">Ўзбекча</a>,</td></tr> <tr><td><a href="/book/zh-tw/v2/GitHub-Scripting-GitHub">繁體中文</a>,</td></tr> </table> </p> <p> Translations started for <table> <tr><td><a href="/book/be/v2/GitHub-Scripting-GitHub">Беларуская</a>,</td></tr> <tr><td><a href="/book/fa/v2/GitHub-Scripting-GitHub" dir="rtl">فارسی</a>,</td></tr> <tr><td><a href="/book/id/v2/GitHub-Scripting-GitHub">Indonesian</a>,</td></tr> <tr><td><a href="/book/it/v2/GitHub-Scripting-GitHub">Italiano</a>,</td></tr> <tr><td><a href="/book/ms/v2/GitHub-Scripting-GitHub">Bahasa Melayu</a>,</td></tr> <tr><td><a href="/book/pt-br/v2/GitHub-Scripting-GitHub">Português (Brasil)</a>,</td></tr> <tr><td><a href="/book/pt-pt/v2/GitHub-Scripting-GitHub">Português (Portugal)</a>,</td></tr> <tr><td><a href="/book/sv/v2/GitHub-Scripting-GitHub">Svenska</a>,</td></tr> <tr><td><a href="/book/tr/v2/GitHub-%c3%96zet">Türkçe</a>.</td></tr> </table> </p> <hr class="sidebar"/> <p> The source of this book is <a href="https://github.com/progit/progit2">hosted on GitHub.</a></br> Patches, suggestions and comments are welcome. </p> </nav> </aside> <div id="content"> <div id="book-chapters"> <a class="dropdown-trigger" id="book-chapters-trigger" data-panel-id="chapters-dropdown" href="#">Chapters ▾</a> <div class='dropdown-panel' id='chapters-dropdown'> <div class='three-column'> <div class="column-left"> <ol class='book-toc'> <li class='chapter'> <h2>1. <a href="/book/en/v2/Getting-Started-About-Version-Control">Getting Started</a></h2> <ol> <li> 1.1 <a href="/book/en/v2/Getting-Started-About-Version-Control">About Version Control</a> </li> <li> 1.2 <a href="/book/en/v2/Getting-Started-A-Short-History-of-Git">A Short History of Git</a> </li> <li> 1.3 <a href="/book/en/v2/Getting-Started-What-is-Git%3F">What is Git?</a> </li> <li> 1.4 <a href="/book/en/v2/Getting-Started-The-Command-Line">The Command Line</a> </li> <li> 1.5 <a href="/book/en/v2/Getting-Started-Installing-Git">Installing Git</a> </li> <li> 1.6 <a href="/book/en/v2/Getting-Started-First-Time-Git-Setup">First-Time Git Setup</a> </li> <li> 1.7 <a href="/book/en/v2/Getting-Started-Getting-Help">Getting Help</a> </li> <li> 1.8 <a href="/book/en/v2/Getting-Started-Summary">Summary</a> </li> </ol> </li> <li class='chapter'> <h2>2. <a href="/book/en/v2/Git-Basics-Getting-a-Git-Repository">Git Basics</a></h2> <ol> <li> 2.1 <a href="/book/en/v2/Git-Basics-Getting-a-Git-Repository">Getting a Git Repository</a> </li> <li> 2.2 <a href="/book/en/v2/Git-Basics-Recording-Changes-to-the-Repository">Recording Changes to the Repository</a> </li> <li> 2.3 <a href="/book/en/v2/Git-Basics-Viewing-the-Commit-History">Viewing the Commit History</a> </li> <li> 2.4 <a href="/book/en/v2/Git-Basics-Undoing-Things">Undoing Things</a> </li> <li> 2.5 <a href="/book/en/v2/Git-Basics-Working-with-Remotes">Working with Remotes</a> </li> <li> 2.6 <a href="/book/en/v2/Git-Basics-Tagging">Tagging</a> </li> <li> 2.7 <a href="/book/en/v2/Git-Basics-Git-Aliases">Git Aliases</a> </li> <li> 2.8 <a href="/book/en/v2/Git-Basics-Summary">Summary</a> </li> </ol> </li> <li class='chapter'> <h2>3. <a href="/book/en/v2/Git-Branching-Branches-in-a-Nutshell">Git Branching</a></h2> <ol> <li> 3.1 <a href="/book/en/v2/Git-Branching-Branches-in-a-Nutshell">Branches in a Nutshell</a> </li> <li> 3.2 <a href="/book/en/v2/Git-Branching-Basic-Branching-and-Merging">Basic Branching and Merging</a> </li> <li> 3.3 <a href="/book/en/v2/Git-Branching-Branch-Management">Branch Management</a> </li> <li> 3.4 <a href="/book/en/v2/Git-Branching-Branching-Workflows">Branching Workflows</a> </li> <li> 3.5 <a href="/book/en/v2/Git-Branching-Remote-Branches">Remote Branches</a> </li> <li> 3.6 <a href="/book/en/v2/Git-Branching-Rebasing">Rebasing</a> </li> <li> 3.7 <a href="/book/en/v2/Git-Branching-Summary">Summary</a> </li> </ol> </li> <li class='chapter'> <h2>4. <a href="/book/en/v2/Git-on-the-Server-The-Protocols">Git on the Server</a></h2> <ol> <li> 4.1 <a href="/book/en/v2/Git-on-the-Server-The-Protocols">The Protocols</a> </li> <li> 4.2 <a href="/book/en/v2/Git-on-the-Server-Getting-Git-on-a-Server">Getting Git on a Server</a> </li> <li> 4.3 <a href="/book/en/v2/Git-on-the-Server-Generating-Your-SSH-Public-Key">Generating Your SSH Public Key</a> </li> <li> 4.4 <a href="/book/en/v2/Git-on-the-Server-Setting-Up-the-Server">Setting Up the Server</a> </li> <li> 4.5 <a href="/book/en/v2/Git-on-the-Server-Git-Daemon">Git Daemon</a> </li> <li> 4.6 <a href="/book/en/v2/Git-on-the-Server-Smart-HTTP">Smart HTTP</a> </li> <li> 4.7 <a href="/book/en/v2/Git-on-the-Server-GitWeb">GitWeb</a> </li> <li> 4.8 <a href="/book/en/v2/Git-on-the-Server-GitLab">GitLab</a> </li> <li> 4.9 <a href="/book/en/v2/Git-on-the-Server-Third-Party-Hosted-Options">Third Party Hosted Options</a> </li> <li> 4.10 <a href="/book/en/v2/Git-on-the-Server-Summary">Summary</a> </li> </ol> </li> <li class='chapter'> <h2>5. <a href="/book/en/v2/Distributed-Git-Distributed-Workflows">Distributed Git</a></h2> <ol> <li> 5.1 <a href="/book/en/v2/Distributed-Git-Distributed-Workflows">Distributed Workflows</a> </li> <li> 5.2 <a href="/book/en/v2/Distributed-Git-Contributing-to-a-Project">Contributing to a Project</a> </li> <li> 5.3 <a href="/book/en/v2/Distributed-Git-Maintaining-a-Project">Maintaining a Project</a> </li> <li> 5.4 <a href="/book/en/v2/Distributed-Git-Summary">Summary</a> </li> </ol> </li> </ol> </div> <div class='column-middle'> <ol class='book-toc'> <li class='chapter'> <h2>6. <a href="/book/en/v2/GitHub-Account-Setup-and-Configuration">GitHub</a></h2> <ol> <li> 6.1 <a href="/book/en/v2/GitHub-Account-Setup-and-Configuration">Account Setup and Configuration</a> </li> <li> 6.2 <a href="/book/en/v2/GitHub-Contributing-to-a-Project">Contributing to a Project</a> </li> <li> 6.3 <a href="/book/en/v2/GitHub-Maintaining-a-Project">Maintaining a Project</a> </li> <li> 6.4 <a href="/book/en/v2/GitHub-Managing-an-organization">Managing an organization</a> </li> <li> 6.5 <a href="/book/en/v2/GitHub-Scripting-GitHub" class="active">Scripting GitHub</a> </li> <li> 6.6 <a href="/book/en/v2/GitHub-Summary">Summary</a> </li> </ol> </li> <li class='chapter'> <h2>7. <a href="/book/en/v2/Git-Tools-Revision-Selection">Git Tools</a></h2> <ol> <li> 7.1 <a href="/book/en/v2/Git-Tools-Revision-Selection">Revision Selection</a> </li> <li> 7.2 <a href="/book/en/v2/Git-Tools-Interactive-Staging">Interactive Staging</a> </li> <li> 7.3 <a href="/book/en/v2/Git-Tools-Stashing-and-Cleaning">Stashing and Cleaning</a> </li> <li> 7.4 <a href="/book/en/v2/Git-Tools-Signing-Your-Work">Signing Your Work</a> </li> <li> 7.5 <a href="/book/en/v2/Git-Tools-Searching">Searching</a> </li> <li> 7.6 <a href="/book/en/v2/Git-Tools-Rewriting-History">Rewriting History</a> </li> <li> 7.7 <a href="/book/en/v2/Git-Tools-Reset-Demystified">Reset Demystified</a> </li> <li> 7.8 <a href="/book/en/v2/Git-Tools-Advanced-Merging">Advanced Merging</a> </li> <li> 7.9 <a href="/book/en/v2/Git-Tools-Rerere">Rerere</a> </li> <li> 7.10 <a href="/book/en/v2/Git-Tools-Debugging-with-Git">Debugging with Git</a> </li> <li> 7.11 <a href="/book/en/v2/Git-Tools-Submodules">Submodules</a> </li> <li> 7.12 <a href="/book/en/v2/Git-Tools-Bundling">Bundling</a> </li> <li> 7.13 <a href="/book/en/v2/Git-Tools-Replace">Replace</a> </li> <li> 7.14 <a href="/book/en/v2/Git-Tools-Credential-Storage">Credential Storage</a> </li> <li> 7.15 <a href="/book/en/v2/Git-Tools-Summary">Summary</a> </li> </ol> </li> <li class='chapter'> <h2>8. <a href="/book/en/v2/Customizing-Git-Git-Configuration">Customizing Git</a></h2> <ol> <li> 8.1 <a href="/book/en/v2/Customizing-Git-Git-Configuration">Git Configuration</a> </li> <li> 8.2 <a href="/book/en/v2/Customizing-Git-Git-Attributes">Git Attributes</a> </li> <li> 8.3 <a href="/book/en/v2/Customizing-Git-Git-Hooks">Git Hooks</a> </li> <li> 8.4 <a href="/book/en/v2/Customizing-Git-An-Example-Git-Enforced-Policy">An Example Git-Enforced Policy</a> </li> <li> 8.5 <a href="/book/en/v2/Customizing-Git-Summary">Summary</a> </li> </ol> </li> <li class='chapter'> <h2>9. <a href="/book/en/v2/Git-and-Other-Systems-Git-as-a-Client">Git and Other Systems</a></h2> <ol> <li> 9.1 <a href="/book/en/v2/Git-and-Other-Systems-Git-as-a-Client">Git as a Client</a> </li> <li> 9.2 <a href="/book/en/v2/Git-and-Other-Systems-Migrating-to-Git">Migrating to Git</a> </li> <li> 9.3 <a href="/book/en/v2/Git-and-Other-Systems-Summary">Summary</a> </li> </ol> </li> <li class='chapter'> <h2>10. <a href="/book/en/v2/Git-Internals-Plumbing-and-Porcelain">Git Internals</a></h2> <ol> <li> 10.1 <a href="/book/en/v2/Git-Internals-Plumbing-and-Porcelain">Plumbing and Porcelain</a> </li> <li> 10.2 <a href="/book/en/v2/Git-Internals-Git-Objects">Git Objects</a> </li> <li> 10.3 <a href="/book/en/v2/Git-Internals-Git-References">Git References</a> </li> <li> 10.4 <a href="/book/en/v2/Git-Internals-Packfiles">Packfiles</a> </li> <li> 10.5 <a href="/book/en/v2/Git-Internals-The-Refspec">The Refspec</a> </li> <li> 10.6 <a href="/book/en/v2/Git-Internals-Transfer-Protocols">Transfer Protocols</a> </li> <li> 10.7 <a href="/book/en/v2/Git-Internals-Maintenance-and-Data-Recovery">Maintenance and Data Recovery</a> </li> <li> 10.8 <a href="/book/en/v2/Git-Internals-Environment-Variables">Environment Variables</a> </li> <li> 10.9 <a href="/book/en/v2/Git-Internals-Summary">Summary</a> </li> </ol> </li> </ol> </div> <div class='column-right'> <ol class='book-toc'> <li class='chapter'> <h2>A1. <a href="/book/en/v2/Appendix-A:-Git-in-Other-Environments-Graphical-Interfaces">Appendix A: Git in Other Environments</a></h2> <ol> <li> A1.1 <a href="/book/en/v2/Appendix-A:-Git-in-Other-Environments-Graphical-Interfaces">Graphical Interfaces</a> </li> <li> A1.2 <a href="/book/en/v2/Appendix-A:-Git-in-Other-Environments-Git-in-Visual-Studio">Git in Visual Studio</a> </li> <li> A1.3 <a href="/book/en/v2/Appendix-A:-Git-in-Other-Environments-Git-in-Visual-Studio-Code">Git in Visual Studio Code</a> </li> <li> A1.4 <a href="/book/en/v2/Appendix-A:-Git-in-Other-Environments-Git-in-IntelliJ-/-PyCharm-/-WebStorm-/-PhpStorm-/-RubyMine">Git in IntelliJ / PyCharm / WebStorm / PhpStorm / RubyMine</a> </li> <li> A1.5 <a href="/book/en/v2/Appendix-A:-Git-in-Other-Environments-Git-in-Sublime-Text">Git in Sublime Text</a> </li> <li> A1.6 <a href="/book/en/v2/Appendix-A:-Git-in-Other-Environments-Git-in-Bash">Git in Bash</a> </li> <li> A1.7 <a href="/book/en/v2/Appendix-A:-Git-in-Other-Environments-Git-in-Zsh">Git in Zsh</a> </li> <li> A1.8 <a href="/book/en/v2/Appendix-A:-Git-in-Other-Environments-Git-in-PowerShell">Git in PowerShell</a> </li> <li> A1.9 <a href="/book/en/v2/Appendix-A:-Git-in-Other-Environments-Summary">Summary</a> </li> </ol> </li> <li class='chapter'> <h2>A2. <a href="/book/en/v2/Appendix-B:-Embedding-Git-in-your-Applications-Command-line-Git">Appendix B: Embedding Git in your Applications</a></h2> <ol> <li> A2.1 <a href="/book/en/v2/Appendix-B:-Embedding-Git-in-your-Applications-Command-line-Git">Command-line Git</a> </li> <li> A2.2 <a href="/book/en/v2/Appendix-B:-Embedding-Git-in-your-Applications-Libgit2">Libgit2</a> </li> <li> A2.3 <a href="/book/en/v2/Appendix-B:-Embedding-Git-in-your-Applications-JGit">JGit</a> </li> <li> A2.4 <a href="/book/en/v2/Appendix-B:-Embedding-Git-in-your-Applications-go-git">go-git</a> </li> <li> A2.5 <a href="/book/en/v2/Appendix-B:-Embedding-Git-in-your-Applications-Dulwich">Dulwich</a> </li> </ol> </li> <li class='chapter'> <h2>A3. <a href="/book/en/v2/Appendix-C:-Git-Commands-Setup-and-Config">Appendix C: Git Commands</a></h2> <ol> <li> A3.1 <a href="/book/en/v2/Appendix-C:-Git-Commands-Setup-and-Config">Setup and Config</a> </li> <li> A3.2 <a href="/book/en/v2/Appendix-C:-Git-Commands-Getting-and-Creating-Projects">Getting and Creating Projects</a> </li> <li> A3.3 <a href="/book/en/v2/Appendix-C:-Git-Commands-Basic-Snapshotting">Basic Snapshotting</a> </li> <li> A3.4 <a href="/book/en/v2/Appendix-C:-Git-Commands-Branching-and-Merging">Branching and Merging</a> </li> <li> A3.5 <a href="/book/en/v2/Appendix-C:-Git-Commands-Sharing-and-Updating-Projects">Sharing and Updating Projects</a> </li> <li> A3.6 <a href="/book/en/v2/Appendix-C:-Git-Commands-Inspection-and-Comparison">Inspection and Comparison</a> </li> <li> A3.7 <a href="/book/en/v2/Appendix-C:-Git-Commands-Debugging">Debugging</a> </li> <li> A3.8 <a href="/book/en/v2/Appendix-C:-Git-Commands-Patching">Patching</a> </li> <li> A3.9 <a href="/book/en/v2/Appendix-C:-Git-Commands-Email">Email</a> </li> <li> A3.10 <a href="/book/en/v2/Appendix-C:-Git-Commands-External-Systems">External Systems</a> </li> <li> A3.11 <a href="/book/en/v2/Appendix-C:-Git-Commands-Administration">Administration</a> </li> <li> A3.12 <a href="/book/en/v2/Appendix-C:-Git-Commands-Plumbing-Commands">Plumbing Commands</a> </li> </ol> </li> </ol> </div> </div> </div> <span class="light" id="edition"> 2nd Edition </span> </div> <div id="main" data-pagefind-filter="category:book" data-pagefind-meta="category:Book" data-pagefind-weight="0.05" data-pagefind-body class="book edition2"> <h1>6.5 GitHub - Scripting GitHub</h1> <div> <h2 id="_scripting_github">Scripting GitHub</h2> <div class="paragraph"> <p>So now we’ve covered all of the major features and workflows of GitHub, but any large group or project will have customizations they may want to make or external services they may want to integrate.</p> </div> <div class="paragraph"> <p>Luckily for us, GitHub is really quite hackable in many ways. In this section we’ll cover how to use the GitHub hooks system and its API to make GitHub work how we want it to.</p> </div> <div class="sect3"> <h3 id="_services_and_hooks">Services and Hooks</h3> <div class="paragraph"> <p>The Hooks and Services section of GitHub repository administration is the easiest way to have GitHub interact with external systems.</p> </div> <div class="sect4"> <h4 id="_services">Services</h4> <div class="paragraph"> <p>First we’ll take a look at Services. Both the Hooks and Services integrations can be found in the Settings section of your repository, where we previously looked at adding Collaborators and changing the default branch of your project. Under the “Webhooks and Services” tab you will see something like <a href="/book/en/v2/ch00/_services_hooks">Services and Hooks configuration section</a>.</p> </div> <div id="_services_hooks" class="imageblock"> <div class="content"> <img src="/book/en/v2/images/scripting-01-services.png" alt="Services and Hooks configuration section"> </div> <div class="title">Figure 129. Services and Hooks configuration section</div> </div> <div class="paragraph"> <p>There are dozens of services you can choose from, most of them integrations into other commercial and open source systems. Most of them are for Continuous Integration services, bug and issue trackers, chat room systems and documentation systems. We’ll walk through setting up a very simple one, the Email hook. If you choose “email” from the “Add Service” dropdown, you’ll get a configuration screen like <a href="/book/en/v2/ch00/_service_config">Email service configuration</a>.</p> </div> <div id="_service_config" class="imageblock"> <div class="content"> <img src="/book/en/v2/images/scripting-02-email-service.png" alt="Email service configuration"> </div> <div class="title">Figure 130. Email service configuration</div> </div> <div class="paragraph"> <p>In this case, if we hit the “Add service” button, the email address we specified will get an email every time someone pushes to the repository. Services can listen for lots of different types of events, but most only listen for push events and then do something with that data.</p> </div> <div class="paragraph"> <p>If there is a system you are using that you would like to integrate with GitHub, you should check here to see if there is an existing service integration available. For example, if you’re using Jenkins to run tests on your codebase, you can enable the Jenkins builtin service integration to kick off a test run every time someone pushes to your repository.</p> </div> </div> <div class="sect4"> <h4 id="_hooks_2">Hooks</h4> <div class="paragraph"> <p>If you need something more specific or you want to integrate with a service or site that is not included in this list, you can instead use the more generic hooks system. GitHub repository hooks are pretty simple. You specify a URL and GitHub will post an HTTP payload to that URL on any event you want.</p> </div> <div class="paragraph"> <p>Generally the way this works is you can setup a small web service to listen for a GitHub hook payload and then do something with the data when it is received.</p> </div> <div class="paragraph"> <p>To enable a hook, you click the “Add webhook” button in <a href="/book/en/v2/ch00/_services_hooks">Services and Hooks configuration section</a>. This will bring you to a page that looks like <a href="/book/en/v2/ch00/_web_hook">Web hook configuration</a>.</p> </div> <div id="_web_hook" class="imageblock"> <div class="content"> <img src="/book/en/v2/images/scripting-03-webhook.png" alt="Web hook configuration"> </div> <div class="title">Figure 131. Web hook configuration</div> </div> <div class="paragraph"> <p>The configuration for a web hook is pretty simple. In most cases you simply enter a URL and a secret key and hit “Add webhook”. There are a few options for which events you want GitHub to send you a payload for — the default is to only get a payload for the <code>push</code> event, when someone pushes new code to any branch of your repository.</p> </div> <div class="paragraph"> <p>Let’s see a small example of a web service you may set up to handle a web hook. We’ll use the Ruby web framework Sinatra since it’s fairly concise and you should be able to easily see what we’re doing.</p> </div> <div class="paragraph"> <p>Let’s say we want to get an email if a specific person pushes to a specific branch of our project modifying a specific file. We could fairly easily do that with code like this:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-ruby" data-lang="ruby">require 'sinatra' require 'json' require 'mail' post '/payload' do push = JSON.parse(request.body.read) # parse the JSON # gather the data we're looking for pusher = push["pusher"]["name"] branch = push["ref"] # get a list of all the files touched files = push["commits"].map do |commit| commit['added'] + commit['modified'] + commit['removed'] end files = files.flatten.uniq # check for our criteria if pusher == 'schacon' && branch == 'ref/heads/special-branch' && files.include?('special-file.txt') Mail.deliver do from 'tchacon@example.com' to 'tchacon@example.com' subject 'Scott Changed the File' body "ALARM" end end end</code></pre> </div> </div> <div class="paragraph"> <p>Here we’re taking the JSON payload that GitHub delivers us and looking up who pushed it, what branch they pushed to and what files were touched in all the commits that were pushed. Then we check that against our criteria and send an email if it matches.</p> </div> <div class="paragraph"> <p>In order to develop and test something like this, you have a nice developer console in the same screen where you set the hook up. You can see the last few deliveries that GitHub has tried to make for that webhook. For each hook you can dig down into when it was delivered, if it was successful and the body and headers for both the request and the response. This makes it incredibly easy to test and debug your hooks.</p> </div> <div id="_web_hook_debug" class="imageblock"> <div class="content"> <img src="/book/en/v2/images/scripting-04-webhook-debug.png" alt="Web hook debugging information"> </div> <div class="title">Figure 132. Web hook debugging information</div> </div> <div class="paragraph"> <p>The other great feature of this is that you can redeliver any of the payloads to test your service easily.</p> </div> <div class="paragraph"> <p>For more information on how to write webhooks and all the different event types you can listen for, go to the GitHub Developer documentation at <a href="https://docs.github.com/en/webhooks-and-events/webhooks/about-webhooks" class="bare" target="_blank" rel="noopener">https://docs.github.com/en/webhooks-and-events/webhooks/about-webhooks</a>.</p> </div> </div> </div> <div class="sect3"> <h3 id="_the_github_api">The GitHub API</h3> <div class="paragraph"> <p> Services and hooks give you a way to receive push notifications about events that happen on your repositories, but what if you need more information about these events? What if you need to automate something like adding collaborators or labeling issues?</p> </div> <div class="paragraph"> <p>This is where the GitHub API comes in handy. GitHub has tons of API endpoints for doing nearly anything you can do on the website in an automated fashion. In this section we’ll learn how to authenticate and connect to the API, how to comment on an issue and how to change the status of a Pull Request through the API.</p> </div> </div> <div class="sect3"> <h3 id="_basic_usage_2">Basic Usage</h3> <div class="paragraph"> <p>The most basic thing you can do is a simple GET request on an endpoint that doesn’t require authentication. This could be a user or read-only information on an open source project. For example, if we want to know more about a user named “schacon”, we can run something like this:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-javascript" data-lang="javascript">$ curl https://api.github.com/users/schacon { "login": "schacon", "id": 70, "avatar_url": "https://avatars.githubusercontent.com/u/70", # … "name": "Scott Chacon", "company": "GitHub", "following": 19, "created_at": "2008-01-27T17:19:28Z", "updated_at": "2014-06-10T02:37:23Z" }</code></pre> </div> </div> <div class="paragraph"> <p>There are tons of endpoints like this to get information about organizations, projects, issues, commits — just about anything you can publicly see on GitHub. You can even use the API to render arbitrary Markdown or find a <code>.gitignore</code> template.</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-javascript" data-lang="javascript">$ curl https://api.github.com/gitignore/templates/Java { "name": "Java", "source": "*.class # Mobile Tools for Java (J2ME) .mtj.tmp/ # Package Files # *.jar *.war *.ear # virtual machine crash logs, see https://www.java.com/en/download/help/error_hotspot.xml hs_err_pid* " }</code></pre> </div> </div> </div> <div class="sect3"> <h3 id="_commenting_on_an_issue">Commenting on an Issue</h3> <div class="paragraph"> <p>However, if you want to do an action on the website such as comment on an Issue or Pull Request or if you want to view or interact with private content, you’ll need to authenticate.</p> </div> <div class="paragraph"> <p>There are several ways to authenticate. You can use basic authentication with just your username and password, but generally it’s a better idea to use a personal access token. You can generate this from the “Applications” tab of your settings page.</p> </div> <div id="_access_token" class="imageblock"> <div class="content"> <img src="/book/en/v2/images/scripting-05-access-token.png" alt="Generate your access token from the “Applications” tab of your settings page"> </div> <div class="title">Figure 133. Generate your access token from the “Applications” tab of your settings page</div> </div> <div class="paragraph"> <p>It will ask you which scopes you want for this token and a description. Make sure to use a good description so you feel comfortable removing the token when your script or application is no longer used.</p> </div> <div class="paragraph"> <p>GitHub will only show you the token once, so be sure to copy it. You can now use this to authenticate in your script instead of using a username and password. This is nice because you can limit the scope of what you want to do and the token is revocable.</p> </div> <div class="paragraph"> <p>This also has the added advantage of increasing your rate limit. Without authenticating, you will be limited to 60 requests per hour. If you authenticate you can make up to 5,000 requests per hour.</p> </div> <div class="paragraph"> <p>So let’s use it to make a comment on one of our issues. Let’s say we want to leave a comment on a specific issue, Issue #6. To do so we have to do an HTTP POST request to <code>repos/<user>/<repo>/issues/<num>/comments</code> with the token we just generated as an Authorization header.</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-javascript" data-lang="javascript">$ curl -H "Content-Type: application/json" \ -H "Authorization: token TOKEN" \ --data '{"body":"A new comment, :+1:"}' \ https://api.github.com/repos/schacon/blink/issues/6/comments { "id": 58322100, "html_url": "https://github.com/schacon/blink/issues/6#issuecomment-58322100", ... "user": { "login": "tonychacon", "id": 7874698, "avatar_url": "https://avatars.githubusercontent.com/u/7874698?v=2", "type": "User", }, "created_at": "2014-10-08T07:48:19Z", "updated_at": "2014-10-08T07:48:19Z", "body": "A new comment, :+1:" }</code></pre> </div> </div> <div class="paragraph"> <p>Now if you go to that issue, you can see the comment that we just successfully posted as in <a href="/book/en/v2/ch00/_api_comment">A comment posted from the GitHub API</a>.</p> </div> <div id="_api_comment" class="imageblock"> <div class="content"> <img src="/book/en/v2/images/scripting-06-comment.png" alt="A comment posted from the GitHub API"> </div> <div class="title">Figure 134. A comment posted from the GitHub API</div> </div> <div class="paragraph"> <p>You can use the API to do just about anything you can do on the website — creating and setting milestones, assigning people to Issues and Pull Requests, creating and changing labels, accessing commit data, creating new commits and branches, opening, closing or merging Pull Requests, creating and editing teams, commenting on lines of code in a Pull Request, searching the site and on and on.</p> </div> </div> <div class="sect3"> <h3 id="_changing_the_status_of_a_pull_request">Changing the Status of a Pull Request</h3> <div class="paragraph"> <p>There is one final example we’ll look at since it’s really useful if you’re working with Pull Requests. Each commit can have one or more statuses associated with it and there is an API to add and query that status.</p> </div> <div class="paragraph"> <p>Most of the Continuous Integration and testing services make use of this API to react to pushes by testing the code that was pushed, and then report back if that commit has passed all the tests. You could also use this to check if the commit message is properly formatted, if the submitter followed all your contribution guidelines, if the commit was validly signed — any number of things.</p> </div> <div class="paragraph"> <p>Let’s say you set up a webhook on your repository that hits a small web service that checks for a <code>Signed-off-by</code> string in the commit message.</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-ruby" data-lang="ruby">require 'httparty' require 'sinatra' require 'json' post '/payload' do push = JSON.parse(request.body.read) # parse the JSON repo_name = push['repository']['full_name'] # look through each commit message push["commits"].each do |commit| # look for a Signed-off-by string if /Signed-off-by/.match commit['message'] state = 'success' description = 'Successfully signed off!' else state = 'failure' description = 'No signoff found.' end # post status to GitHub sha = commit["id"] status_url = "https://api.github.com/repos/#{repo_name}/statuses/#{sha}" status = { "state" => state, "description" => description, "target_url" => "http://example.com/how-to-signoff", "context" => "validate/signoff" } HTTParty.post(status_url, :body => status.to_json, :headers => { 'Content-Type' => 'application/json', 'User-Agent' => 'tonychacon/signoff', 'Authorization' => "token #{ENV['TOKEN']}" } ) end end</code></pre> </div> </div> <div class="paragraph"> <p>Hopefully this is fairly simple to follow. In this web hook handler we look through each commit that was just pushed, we look for the string 'Signed-off-by' in the commit message and finally we POST via HTTP to the <code>/repos/<user>/<repo>/statuses/<commit_sha></code> API endpoint with the status.</p> </div> <div class="paragraph"> <p>In this case you can send a state ('success', 'failure', 'error'), a description of what happened, a target URL the user can go to for more information and a “context” in case there are multiple statuses for a single commit. For example, a testing service may provide a status and a validation service like this may also provide a status — the “context” field is how they’re differentiated.</p> </div> <div class="paragraph"> <p>If someone opens a new Pull Request on GitHub and this hook is set up, you may see something like <a href="/book/en/v2/ch00/_commit_status">Commit status via the API</a>.</p> </div> <div id="_commit_status" class="imageblock"> <div class="content"> <img src="/book/en/v2/images/scripting-07-status.png" alt="Commit status via the API"> </div> <div class="title">Figure 135. Commit status via the API</div> </div> <div class="paragraph"> <p>You can now see a little green check mark next to the commit that has a “Signed-off-by” string in the message and a red cross through the one where the author forgot to sign off. You can also see that the Pull Request takes the status of the last commit on the branch and warns you if it is a failure. This is really useful if you’re using this API for test results so you don’t accidentally merge something where the last commit is failing tests.</p> </div> </div> <div class="sect3"> <h3 id="_octokit">Octokit</h3> <div class="paragraph"> <p>Though we’ve been doing nearly everything through <code>curl</code> and simple HTTP requests in these examples, several open-source libraries exist that make this API available in a more idiomatic way. At the time of this writing, the supported languages include Go, Objective-C, Ruby, and .NET. Check out <a href="https://github.com/octokit" class="bare" target="_blank" rel="noopener">https://github.com/octokit</a> for more information on these, as they handle much of the HTTP for you.</p> </div> <div class="paragraph"> <p>Hopefully these tools can help you customize and modify GitHub to work better for your specific workflows. For complete documentation on the entire API as well as guides for common tasks, check out <a href="https://docs.github.com/" class="bare" target="_blank" rel="noopener">https://docs.github.com/</a>.</p> </div> </div> <div id="nav"><a href="/book/en/v2/GitHub-Managing-an-organization">prev</a> | <a href="/book/en/v2/GitHub-Summary">next</a></div> </div> </div> </div> </div> <footer> <div class="site-source"> <a href="/site">About this site</a><br> Patches, suggestions, and comments are welcome. </div> <div class="sfc-member"> Git is a member of <a href="/sfc">Software Freedom Conservancy</a> </div> </footer> <a href="#top" class="no-js scrollToTop" id="scrollToTop" data-label="Scroll to top"> <img src="/images/icons/chevron-up@2x.png" width="20" height="20" alt="scroll-to-top"/> </a> <script src="/js/jquery-1.7.1.min.js"></script> <script src="/js/jquery-ui-1.8.18.custom.min.js"></script> <script src="/js/jquery.defaultvalue.js"></script> <script src="/js/session.min.js"></script> <script src="/js/application.min.js"></script> </div> </body> </html>