diff --git a/book/06-github/sections/5-scripting.asc b/book/06-github/sections/5-scripting.asc index 4c099645..6a6976dc 100644 --- a/book/06-github/sections/5-scripting.asc +++ b/book/06-github/sections/5-scripting.asc @@ -1,63 +1,49 @@ -=== Scripting GitHub +=== Написание скриптов для GitHub -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. +К этому моменту вы уже рассмотрели особенности Github и узнали как устроен рабочий процесс. Однако для больших команд разработки и крупных проектов может быть необходима возможность настройки интеграции с внешними сервисами. -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. +К счастью для нас Github достаточно гибкий и расширяемый инструмент. В этом разделе вы научитесь использовать веб хуки и API Github, чтобы вывести вашу работу с данным инструментом на новый уровень. -==== Services and Hooks +==== Сервисы и хуки -The Hooks and Services section of GitHub repository administration is the easiest way to have GitHub interact with external systems. +Самый простой способ управления сервисами и веб хуками - это перейти в панель администрирования вашего Git-репозитория и настроить взаимодействие с внешними сервисами. -===== Services - -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 <>. +===== Сервисы +Сначала разберемся с сервисами. Настроить сервисы и веб хуки можно в пункте "Settings" вашего репозитория, где ранее рассматривались участники проекта и изменение основной ветки по умолчанию. Нажмите на вкладку "Webhooks and Services" и вы увидите раздел как на рисунке <>. [[r_services_hooks]] -.Services and Hooks configuration section -image::images/scripting-01-services.png[Services and hooks] +.Раздел конфигурации сервисов и хуков +image::images/scripting-01-services.png[Раздел конфигурации сервисов и хуков] -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 <>. +Здесь можно выбрать десятки разных сервисов, большинство из которых представляют собой интеграцию с другими коммерческими системами и системами с открытым исходным кодом. +Это преимущественно сервисы непрерывной интеграции, трекеры проблем и багов, чаты и сервисы для ведения документации. Мы рассмотрим самый простой - сервис электронной почты. Если вы выберете "email" в выпадающем списке всплывающего окна "Add Service", то получите страницу с настройками как на рисунке <>. [[r_service_config]] -.Email service configuration -image::images/scripting-02-email-service.png[Email service] +.Настройка сервиса электронной почты +image::images/scripting-02-email-service.png[Сервис электронной почты] -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. +Нажав на кнопку "Add Service", вы будете получать электронную почту, на указанный адрес, каждый раз когда кто-нибудь будет отправлять изменения в ваш репозиторий. Сервисы могут слушать большое количество разнообразных типов событий, но наиболее используемый тип, который вызывается при отправке изменений в репозиторий. Каждый тип событий представляет собой определенный набор данных, который впоследствии обрабатывается настраиваемыми сервисами. -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. +Если вы используете какую-нибудь систему и хотели бы интегрировать ее с GitHub, то сначала вам необходимо убедиться, что для этого существует свой сервис. Например, если вы используете Jenkins для запуска тестов, вы можете использовать встроенный сервис Jenkins, чтобы запускать ваши тесты каждый раз когда кто-то будет отправлять свои изменения в ваш репозиторий. -===== Hooks +===== Веб хуки -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. +Чтобы более гибко настроить взаимодействие или если необходимый вам сервис не был найден в выпадающем списке, вы можете использовать универсальную систему веб хуков. Веб хуки GitHub репозитория очень просты. Вы указываете URL, выбираете событие и GitHub отправляет данные этого события посредством HTTP-запроса. -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. +Как правило, это работает следующим образом. Вы настраиваете небольшой веб-сервис принимающий данные хука и затем производите с полученными данными какие-либо манипуляции. -To enable a hook, you click the «Add webhook» button in <>. -This will bring you to a page that looks like <>. +Для того, чтобы добавить веб хук, нажмите на кнопку "Add webhook" в <>. Перед вами откроется страница как на рисунке <>. [[r_web_hook]] -.Web hook configuration -image::images/scripting-03-webhook.png[Web hook] +.Настройка веб хука +image::images/scripting-03-webhook.png[Настройка веб хука] -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 `push` event, when someone pushes new code to any branch of your repository. +Настройка не представляет из себя ничего сложного. В большинстве случаев вы просто вводите URL и секретный ключ, затем нажимаете "Add webhook". В качестве параметра указывается событие, по возникновению которого GitHub будет отправлять данные на ваш веб-сервис. По умолчанию это событие происходящее при отправке изменений в любую ветку вашего репозитория. -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. +Рассмотрим небольшой пример веб-сервиса, настроенного на обработку хука. Мы будем использовать Ruby фреймворк называющийся Sinatra, который достаточно прост и позволяет с легкостью сделать то, что вам нужно. -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: +Укажем, что вы хотите получать письмо на электронную почту если какой-то определенный участник проекта отправил изменения в определенную ветку нашего проекта, изменив +определенный файл. Сделать это можно, примерно так: [source,ruby] ---- @@ -93,37 +79,30 @@ post '/payload' do end ---- -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. +Вы получаете данные в формате JSON от GitHub, смотрите кто отправил их, в какую ветку отправлены эти изменения и какие файлы были изменены во всех этих коммитах, которые были вами получены. Затем вы проверяете их по заданным критериям и отправляете письмо на электронную почту, если всё совпадает. -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. +В целях разработки и тестирования, вы можете воспользоваться консолью разработчика на той же самой странице, где вы настраивали ваш хук. Здесь можно посмотреть ранее отправленные данныe. Для выполненных хуков, представлена информация когда это было сделано, успешность выполнения, тело и заголовки как запроса, так и ответа обратно от вашего веб-сервиса. Это позволяет невероятно просто тестировать и отлаживать ваши веб хуки. [[r_web_hook_debug]] -.Web hook debugging information -image::images/scripting-04-webhook-debug.png[Webhook debug] +.Отладочная информация о веб хуках +image::images/scripting-04-webhook-debug.png[Отладка веб хуков] -The other great feature of this is that you can redeliver any of the payloads to test your service easily. +Другая полезная возможность состоит в том, что вы можете переадресовать ранее отправленное событие на другой веб-сервис для отладки. -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 https://developer.github.com/webhooks/[^]. +За дополнительной информацией как писать хуки и описания типов событий, которые вы можете прослушивать, перейдите в документацию GitHub-разработчика https://developer.github.com/webhooks/[^]. -==== The GitHub API +==== API GitHub (((GitHub, API))) -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? -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. +Сервисы и хуки дают вам способ принятия уведомлений о событиях которые произошли с вашим репозиторием, но, что если вам нужно немного больше информации об этих событиях? +Что если вам нужно автоматизировать что-нибудь вроде добавления участников или названия проблемы? + +Вот где GitHub API приходится кстати. GitHub имеет множество API-методов для большинства вещей, чтобы автоматизировать все, что вы можете сделать вручную на сайте. В этом разделе вы научитесь проходить аутентификацию и подключаться к API, комментировать проблемы и менять статус запроса на слияние. -==== Basic Usage +==== Основы использования -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: +Самая простая, базовая вещь, которую вы можете сделать - это простой GET-запрос к API, при котором не требуется аутентификация. То есть вы можете делать то, что может неавторизованный пользователь в общедоступном репозитории. Для примера, если вы хотите узнать больше о пользователе с именем "schacon", вы можете написать такой код: [source,javascript] ---- @@ -141,8 +120,9 @@ $ curl https://api.github.com/users/schacon } ---- -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 `.gitignore` template. + +Есть множество API-методов позволяющих получать информацию об организациях, проектах, проблемах, коммитах и абсолютно всего, что вы можете публично посмотреть на GitHub. +Вы можете даже использовать API, чтобы отобразить Markdown-разметку или найти шаблон .gitignore файла. [source,javascript] ---- @@ -166,32 +146,31 @@ hs_err_pid* ---- -==== Commenting on an Issue +==== Написание комментариев в разделе проблем -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. +Если вы хотите выполнить какое-либо действие на сайте, такое как комментирование проблемы или создание запроса на слияние, или если вы хотите просмотреть приватные данные, доступные для чтения вашему аккаунту, то вам необходимо пройти аутентификацию. -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. +Есть несколько способов аутентификации. +Самый простой представляет собой ввод вашего логина и пароля, но обычно гораздо более разумной идеей является использование личного токена доступа. +Вы можете сгенерировать его во вкладке "Applications", настроек вашего аккаунта. [[r_access_token]] -.Generate your access token from the «Applications» tab of your settings page -image::images/scripting-05-access-token.png[Access Token] +.Генерация вашего токена личного доступа во вкладке "Applications" из настроек страницы пользователя +image::images/scripting-05-access-token.png[Токен доступа] -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. +Здесь будут запрошены какие права вы хотите предоставить вашему токену, а также описание к нему. +Не пренебрегайте оставлять содержательное описание к токену, потому что в будущем вы можете захотеть удалить неиспользуемый токен доступа и описание к нему может сильно помочь выбрать корректный из списка. -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. +GitHub показывает токен доступа только один раз, поэтому сразу скопируйте его. +Теперь вы можете пройти аутентификацию используя токен доступа в ваших скриптах, вместо ввода логина и пароля. Создание личного токена доступа также позволяет выполнять запросы только в рамках установленных прав к этому токену, а также его в любой момент можно отозвать. -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. +Используя аутентификацию вы увеличиваете свой лимит запросов. +Без аутентификации, вы можете делать только 60 запросов в час. +Но если вы прошли аутентификацию, этот лимит повышается до 5,000 запросов в час. -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 `repos///issues//comments` with the token we just generated as an Authorization header. +Теперь давайте оставим комментарий к одной из проблем. +Предположим вы хотите оставить комментарий к определенной проблеме, Issue #6. +Для того, чтобы сделать это вы отправляете HTTP Post-запрос к `repos///issues//comments`, используя ранее сгенерированный токен в поле заголовка "Authorization" вашего запроса. [source,javascript] ---- @@ -215,23 +194,35 @@ $ curl -H "Content-Type: application/json" \ } ---- -Now if you go to that issue, you can see the comment that we just successfully posted as in <>. +Теперь, если вы перейдете к разделу проблем, вы увидите, что появился комментарий, который вы только что успешно отправили в <>. [[r_api_comment]] -.A comment posted from the GitHub API -image::images/scripting-06-comment.png[API Comment] +.Комментарий отправленный через API GitHub +image::images/scripting-06-comment.png[Комментарий отправленный через API GitHub] + +Вы можете использовать API для чего угодно, что можете выполнить на самом сайте: -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. +* создавать и настраивать вехи +* присоединять участников к проблемам +* создавать запросы на слияние +* создавать и редактировать метки +* получать доступ к информации содержащейся в коммитах +* создавать новые коммиты и ветки +* открывать, закрывать и сливать запросы на слияние +* создавать и редактировать группы участников +* комментировать определенные строки кода к запросам на слияние +* искать другие проекты на сайте -==== Changing the Status of a Pull Request +Все это лишь неполный список того, что в можете делать. -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. +==== Изменение статуса запроса на слияние -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. +Рассмотрим еще один, самый полезный пример, который вам пригодится при работе с запросами на слияние. +Каждый коммит может иметь один или несколько статусов ассоциированных с ним. Существуют методы API, позволяющие добавлять или запрашивать этот статус. -Let's say you set up a webhook on your repository that hits a small web service that checks for a `Signed-off-by` string in the commit message. +Этими методами в основном пользуются системы непрерывной интеграции и сервисы тестирования, чтобы оперативно тестировать тот код, который только что был отправлен в репозиторий, а затем вернуть отчет прошел ли этот код все тесты или нет. Вы также можете проверять соответствует ли сообщение коммита надлежащему форматированию, соблюдает ли отправитель все ваши правила контрибуции и корректно ли подписан коммит -- все что угодно. + +Предположим вы настраиваете хук для вашего репозитория, который получает ваш веб-сервис и проверяете есть ли строка `Signed-off-by` в сообщении к коммиту. [source,ruby] ---- @@ -276,27 +267,30 @@ post '/payload' do end ---- -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 `/repos///statuses/` API endpoint with the status. +Надеюсь, для вас не составит труда разобраться, что здесь происходит. +Обработчик этого хука просматривает каждый коммит, который был отправлен в репозиторий и ищет строку 'Signed-off-by' в сообщении к коммиту, далее отправляет HTTP POST-запрос, содержащий статус выполнения, к `/repos///statuses/`. + +В данном случае статус включает в себя: + +* состояние ('success', 'failure', 'error') +* описание что произошло +* конечный URL, по которому пользователь может перейти за дополнительной информацией +* контекст, в случае если один коммит содержит несколько состояний одновременно -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. +Для примера, сервис тестирования может передавать свой статус к коммиту, а сервис валидации добавляет к нему свой статус -- поле «context» как раз различает эти статусы. -If someone opens a new Pull Request on GitHub and this hook is set up, you may see something like <>. +Если кто-то открывает запрос на слияние, на GitHub и для этого настроен веб хук, то вы можете увидеть <>. [[r_commit_status]] -.Commit status via the API -image::images/scripting-07-status.png[Commit status] +.Статус коммита через API +image::images/scripting-07-status.png[Статус коммита через API] -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. +Можно заметить маленькую зеленую галочку рядом с коммитом, которая указывает, что в тексте его сообщения содержится строка "Signed-off-by", а также красный крестик рядом с другим коммитом, который не был корректно подписан. Обратите внимание, что запрос на слияние принимает статус последнего коммита в ветке и предупреждает вас, если в нем содержатся ошибки. Использовать API GitHub для тестирования очень полезно, потому что это позволяет вам увидеть ошибки, которые вы скорее всего не хотели бы слить с вашей долгоживущей веткой. ==== Octokit -Though we've been doing nearly everything through `curl` 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 https://github.com/octokit[^] for more information on these, as they handle much of the HTTP for you. +Хоть вы и можете делать практически все запросы к API используя обычный `curl`, посредством простых HTTP-запросов, как в рассмотренных нами выше примерах, все же существует библиотека с открытым исходным кодом, которая значительно облегчит использования API и сделает работу с ним более интуитивно-понятной. +На момент написания, эта библиотека поддерживается такими языками как Go, Objective-C, Ruby и .Net. +За получением более подробной информации переходите на https://github.com/octokit[^], чтобы дать возможность библиотеке составлять эти HTTP-запросы за вас. -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 https://developer.github.com[^]. +Надеемся, что рассмотренные возможности помогут вам более гибко настроить GitHub под ваш рабочий процесс. Для получения более полной документации к API, а также описанию общих задач, переходите на https://developer.github.com[^].