From 9f02ceb8049dfff33e4f68b79bf8fb474a8774b2 Mon Sep 17 00:00:00 2001 From: Viktor Yegay Date: Thu, 29 Sep 2022 17:10:30 +0500 Subject: [PATCH 1/2] =?UTF-8?q?=D0=9F=D0=B5=D1=80=D0=B5=D0=B2=D0=B5=D1=81?= =?UTF-8?q?=D1=82=D0=B8=20=D1=80=D0=B0=D0=B7=D0=B4=D0=B5=D0=BB=206.5=20Scr?= =?UTF-8?q?ipting=20GitHub?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- book/06-github/sections/5-scripting.asc | 192 ++++++++++++------------ status.json | 4 +- 2 files changed, 98 insertions(+), 98 deletions(-) diff --git a/book/06-github/sections/5-scripting.asc b/book/06-github/sections/5-scripting.asc index 4c099645..6e61eedf 100644 --- a/book/06-github/sections/5-scripting.asc +++ b/book/06-github/sections/5-scripting.asc @@ -1,63 +1,63 @@ -=== 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 действительно можно взломать во многих отношениях. +В этом разделе мы расскажем, как использовать систему хуков 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. +Раздел Hooks and Services администрирования репозитория GitHub -- это самый простой способ взаимодействия GitHub с внешними системами. -===== 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] -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] -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»), указанный нами адрес электронной почты будет получать электронное письмо каждый раз, когда кто-то отправляет в репозиторий. +Сервисы могут прослушивать множество различных типов событий, но большинство из них прослушивают только push-события, а затем что-то делают с этими данными. -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 на этот URL-адрес для любого события, которое вы хотите. -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. +Как правило, это работает так: вы можете настроить небольшой веб-сервис для прослушивания полезных данных хука GitHub, а затем что-то делать с данными, когда они будут получены. -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] -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 отправлял вам полезные данные -- по умолчанию вы получаете полезные данные только для события `push`, когда кто-то отправляет новый код в любую ветку вашего репозитория. -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 +93,37 @@ 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. +Чтобы разработать и протестировать что-то подобное, у вас есть хорошая консоль разработчика на том же экране, где вы устанавливаете связь. +Вы можете увидеть последние несколько доставок, которые GitHub пытался сделать для этого вебхука. +Для каждого хука вы можете узнать, когда он был доставлен, если он был успешным, а также тело и заголовки как для запроса, так и для ответа. +Это делает невероятно простым тестирование и отладку ваших хуков. [[r_web_hook_debug]] -.Web hook debugging information +.Информация об отладке вебхуков image::images/scripting-04-webhook-debug.png[Webhook debug] -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 Developer по адресу https://developer.github.com/webhooks/[^]. -==== The GitHub API +==== GitHub API (((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? +Сервисы и хуки дают вам возможность получать push-уведомления о событиях, происходящих в ваших репозиториях, но что, если вам нужна дополнительная информация об этих событиях? +Что, если вам нужно автоматизировать что-то вроде добавления соавторов или маркировки проблем? -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. +Вот где API GitHub пригодится. +GitHub имеет множество конечных точек API для автоматического выполнения почти всего, что вы можете делать на веб-сайте. +В этом разделе мы узнаем, как пройти аутентификацию и подключиться к 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 на конечную точку, не требующую аутентификации. +Это может быть пользовательская или доступная только для чтения информация о проекте с открытым исходным кодом. +Например, если мы хотим узнать больше о пользователе с именем «schacon», мы можем запустить что-то вроде этого: [source,javascript] ---- @@ -141,8 +141,8 @@ $ 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. +Существует множество подобных конечных точек для получения информации об организациях, проектах, проблемах, коммитах -- почти обо всём, что вы можете публично увидеть на GitHub. +Вы даже можете использовать API для визуализации произвольного Markdown или найти шаблон `.gitignore`. [source,javascript] ---- @@ -166,32 +166,32 @@ 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 +.Сгенерируйте токен доступа на вкладке «Приложения» («Applications») на странице настроек image::images/scripting-05-access-token.png[Access Token] -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 запросами в час. +Если вы аутентифицируетесь, вы можете делать до 5000 запросов в час. -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. +Итак, давайте воспользуемся им, чтобы прокомментировать одну из наших проблем. +Допустим, мы хотим оставить комментарий к конкретной проблеме, Проблема №6 (Issue #6). +Для этого нам нужно выполнить HTTP-запрос POST к `repos///issues//comments` с токеном, который мы только что сгенерировали в качестве заголовка авторизации. [source,javascript] ---- @@ -215,23 +215,23 @@ $ 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 +.Комментарий, отправленный из GitHub API image::images/scripting-06-comment.png[API Comment] -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. +Вы можете использовать API, чтобы делать практически всё, что вы можете делать на веб-сайте: создавать и устанавливать вехи (milestones), назначать людей для проблем и запросов на слияние, создавать и изменять метки, получать доступ к данным коммитов, создавать новые коммиты и ветки, открывать, закрывать или объединение запросов на слияние, создание и редактирование команд, комментирование строк кода в запросе на слияние, поиск по сайту и так далее. -==== 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. +Есть ещё один последний пример, который мы рассмотрим, так как он действительно полезен, если вы работаете с запросами на слияние. +С каждым коммитом может быть связан один или несколько статусов, и существует API для добавления и запроса этого статуса. -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 +276,27 @@ 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» в сообщении коммита и, наконец, отправляем POST через HTTP в `/repos// /statuses/` Конечная точка API со статусом. -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. +В этом случае вы можете отправить состояние («успех» ('success'), «сбой» ('failure'), «ошибка» ('error')), описание того, что произошло, целевой URL-адрес, по которому пользователь может перейти для получения дополнительной информации, и «контекст» в случае наличия нескольких статусов за один коммит. +Например, сервис тестирования может предоставить статус, а сервис проверки, подобная этой, также может предоставить статус — поле «контекст» — это то, как они различаются. -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 +.Статус коммита через API image::images/scripting-07-status.png[Commit status] -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 для результатов тестирования, чтобы случайно не объединить что-то, где последний коммит не прошел тесты. ==== 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. +Хотя в этих примерах мы делали почти всё с помощью `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[^]. diff --git a/status.json b/status.json index da014ffd..d7a1809b 100644 --- a/status.json +++ b/status.json @@ -51,12 +51,12 @@ "sections/maintaining.asc": 100 }, "06-github": { - "ch06-github.asc": 80, + "ch06-github.asc": 100, "sections/1-setting-up-account.asc": 100, "sections/2-contributing.asc": 100, "sections/3-maintaining.asc": 100, "sections/4-managing-organization.asc": 100, - "sections/5-scripting.asc": 0 + "sections/5-scripting.asc": 100 }, "07-git-tools": { "ch07-git-tools.asc": 100, From 5b0c63d637eb85a4b21f2fc93ef8262a495f5bab Mon Sep 17 00:00:00 2001 From: Viktor Yegay Date: Mon, 10 Oct 2022 22:56:32 +0500 Subject: [PATCH 2/2] =?UTF-8?q?=D0=9C=D0=B5=D0=BB=D0=BA=D0=B8=D0=B5=20?= =?UTF-8?q?=D0=B8=D1=81=D0=BF=D1=80=D0=B0=D0=B2=D0=BB=D0=B5=D0=BD=D0=B8?= =?UTF-8?q?=D1=8F?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- book/06-github/sections/5-scripting.asc | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/book/06-github/sections/5-scripting.asc b/book/06-github/sections/5-scripting.asc index 6e61eedf..28e80699 100644 --- a/book/06-github/sections/5-scripting.asc +++ b/book/06-github/sections/5-scripting.asc @@ -36,7 +36,7 @@ image::images/scripting-02-email-service.png[Email service] ===== Хуки -Если вам нужно что-то более конкретное или вы хотите интегрироваться с сервисом или сайтом, не включенным в этот список, вы можете вместо этого использовать более общую систему хуков. +Если вам нужно что-то более конкретное или вы хотите интегрироваться с сервисом или сайтом, не включённым в этот список, вы можете вместо этого использовать более общую систему хуков. Хуки репозитория GitHub довольно просты. Вы указываете URL-адрес, и GitHub отправит полезные данные HTTP на этот URL-адрес для любого события, которое вы хотите. @@ -56,7 +56,7 @@ image::images/scripting-03-webhook.png[Web hook] Давайте рассмотрим небольшой пример веб-сервиса, который вы можете настроить для обработки вебхука. Мы будем использовать веб-фреймворк Ruby Sinatra, так как он довольно лаконичен, и вы сможете легко увидеть, что мы делаем. -Допустим, мы хотим получать электронное письмо, если конкретный человек отправляет на определенную ветку нашего проекта, изменённый определенный файл. +Допустим, мы хотим получать электронное письмо, если конкретный человек отправляет на определённую ветку нашего проекта, изменённый определённый файл. Мы могли бы довольно легко сделать это с помощью такого кода: [source,ruby] @@ -190,7 +190,7 @@ GitHub покажет вам токен только один раз, поэто Если вы аутентифицируетесь, вы можете делать до 5000 запросов в час. Итак, давайте воспользуемся им, чтобы прокомментировать одну из наших проблем. -Допустим, мы хотим оставить комментарий к конкретной проблеме, Проблема №6 (Issue #6). +Допустим, мы хотим оставить комментарий к конкретной проблеме № 6 (Issue #6). Для этого нам нужно выполнить HTTP-запрос POST к `repos///issues//comments` с токеном, который мы только что сгенерировали в качестве заголовка авторизации. [source,javascript]