GitHub Projects — управление задачами AI-агентов

Практическое руководство по использованию GitHub Projects как системы управления задачами AI-агентов: от доски со статусами до автоматизации через API, GitHub Actions и Agentic Workflows.

Личная доска без API и автоматизации

Для начала можно вести только свои задачи. Понадобятся аккаунт GitHub и право создать Project у пользователя либо в организации. Откройте Projects, создайте проект и выберите таблицу (Table). Видимость проекта проверьте отдельно: она не обязана совпадать с видимостью репозитория.

Добавьте три конкретные задачи, например прочитать README нужного инструмента, проверить способ установки и сохранить вывод о применимости. На этом этапе достаточно черновых элементов (draft items) с описанием результата. Они принадлежат проекту и ещё не являются issues репозитория.

Для работы с файлами добавьте существующую issue через её адрес либо превратите подходящий черновик в issue нужного репозитория. Проверьте адрес новой карточки и права на этот репозиторий. Переход к issue нужен, когда задачу важно обсуждать и связывать с изменениями кода.

Создайте представление Board и сгруппируйте его по Status. Для простой очереди достаточно трёх смыслов: работа ещё не начата, выполняется, результат проверен. Переместите одну карточку в работу, выполните её и сохраните подтверждение в описании или связанной issue. На доске должно быть видно правильное состояние той же задачи.

Изменение статуса не запускает агента, не создаёт PR и не проверяет результат. Личная доска полезна уже без этих интеграций: вы видите очередь и не теряете смысл задачи. Дальнейшие разделы описывают более сложный командный процесс.

Личный проект, API-мутации и агентные workflows при подготовке не создавались. Действия основаны на документации; код конфигурации проверен по структуре, без облачного исполнения.

Как GitHub Projects помогает управлять агентами

GitHub Projects хранит issues, pull requests и черновые задачи в адаптируемом проекте. Одни и те же элементы можно показывать в виде таблицы, канбан-доски или дорожной карты, фильтровать, сортировать, группировать и дополнять пользовательскими полями.

Для процесса с AI-агентами это даёт четыре опоры:

• issue хранит постановку задачи, ограничения и критерии приёмки;
• поле статуса показывает этап выполнения;
• связь issue с pull request сохраняет трассируемость изменений;
• представления позволяют отдельно показать очередь агента и задачи, ожидающие человеческого ревью.

flowchart LR
    A["Человек создаёт issue"] --> B["Задача попадает в Project"]
    B --> C["Агент выполняет задачу"]
    C --> D["Агент открывает pull request"]
    D --> E["Человек проверяет изменения"]
    E --> F["Merge или возврат на доработку"]
    F --> B

GitHub Projects выступает журналом состояния процесса. Способ запуска агента зависит от выбранного инструмента: GitHub Copilot, внешнего coding-агента, собственного приложения или Agentic Workflow.

Поля и представления проекта

Представления

GitHub официально поддерживает три основных макета:

• Table — таблица с полями, фильтрами, сортировкой и группировкой;
• Board — канбан-доска, обычно сгруппированная по статусу;
• Roadmap — временная шкала для задач с датами.

Практичный набор представлений:

Поля проекта

Минимальная схема:

Не создавайте одновременно несколько полей с одинаковым смыслом. Например, два независимых поля Priority быстро приводят к противоречиям.

Поля issues на уровне организации

Issue Fields хранят структурированные данные непосредственно в issue и действуют во всех репозиториях организации. Доступны четыре типа: single-select, текст, число и дата.

Их отличие от полей проекта:

Организация может создать до 25 Issue Fields, а single-select — содержать до 100 вариантов. Проект поддерживает до 50 полей суммарно, включая системные и Issue Fields. Для публичных и внутренних проектов учитывайте видимость поля: поля с режимом Organization only там не отображаются.

Настройка рабочего процесса

Создайте проект

Откройте вкладку Projects у пользователя или организации, создайте проект и выберите Table либо Board. Название должно показывать назначение, например Agent Tasks — Backend.

Настройте статусы

Рабочая последовательность:

1. Backlog — задача зафиксирована, но ещё не готова к выполнению.
2. Todo — есть контекст и критерии приёмки.
3. In Progress — агент начал работу.
4. In Review — pull request открыт и ожидает человека.
5. Done — результат принят по критериям команды. Закрытая карточка и объединённый PR — события, которые могут менять статус; их смысл нужно согласовать с процессом приёмки.

Отдельный статус Assigned to Agent полезен только тогда, когда между назначением и фактическим стартом регулярно возникает очередь.

Опишите контракт задачи

Хорошая задача для агента содержит:

## Контекст
Почему изменение нужно и какое поведение существует сейчас.

## Требования
- Конкретный результат
- Ограничения реализации
- Обработка ошибок

## Критерии приёмки
- Какие тесты должны проходить
- Какой результат должен увидеть пользователь

## Область изменений
- src/...
- tests/...

Размер задачи должен позволять проверить её одним pull request. Большую инициативу разбейте на связанные issues или sub-issues.

Настройте автоматическое добавление

GitHub Projects позволяет автоматически добавлять элементы из выбранного репозитория, когда они соответствуют заданному фильтру. Например, в проект можно направлять открытые issues с меткой agent-task.

Встроенные автоматизации

В меню проекта Workflows доступны встроенные правила, которые реагируют на события и меняют статус элементов.

При создании проекта по умолчанию включены два правила:

• закрытый issue или pull request получает статус Done;
• объединённый pull request получает статус Done.

Дополнительно можно настроить:

• статус при добавлении элемента в проект;
• закрытие issue после перевода элемента в выбранный статус;
• автоматическое добавление элементов по фильтру репозитория;
• архивирование элементов, соответствующих заданным критериям.

Автоматизация через API и Actions

Для управления Projects используется GraphQL API. Перед изменением поля нужно получить идентификаторы проекта, элемента и поля. Для поля single-select дополнительно нужен ID выбранного варианта, а для поля iteration — ID итерации.

Порядок операций:

1. Найти node ID проекта.
2. Получить поля проекта и ID вариантов single-select.
3. Добавить issue или pull request через addProjectV2ItemById.
4. Отдельным запросом обновить поле через updateProjectV2ItemFieldValue.

Создание элемента и изменение поля выполняйте отдельными запросами: для второго нужен ID элемента из результата первого. Не подставляйте номер issue вместо node ID элемента проекта.

Для личного classic-токена документация указывает read:project для чтения и project для чтения и мутаций. У GitHub App права проверяются в его конфигурации; названия classic scopes нельзя механически переносить на права приложения. Официальная документация указывает два варианта: Personal Access Token (classic) пользователя или installation access token приложения GitHub App. Если вы решили подключить GitHub CLI для изменения Projects, документация показывает следующий способ запроса доступа. Для одного чтения используйте read:project; не меняйте существующую авторизацию без проверки нужного аккаунта:

gh auth login --scopes "project"

Пример структуры мутации для статуса:

mutation {
  updateProjectV2ItemFieldValue(
    input: {
      projectId: "PROJECT_ID"
      itemId: "ITEM_ID"
      fieldId: "STATUS_FIELD_ID"
      value: { singleSelectOptionId: "OPTION_ID" }
    }
  ) {
    projectV2Item {
      id
    }
  }
}

Поля Assignees, Labels, Milestone и Repository принадлежат самому issue или pull request. Их нельзя менять через updateProjectV2ItemFieldValue; используйте соответствующие мутации для issue и pull request:

• addAssigneesToAssignable;
• removeAssigneesFromAssignable;
• addLabelsToLabelable;
• removeLabelsFromLabelable;
• updateIssue;
• updatePullRequest;
• transferIssue.

GitHub Agentic Workflows

GitHub Agentic Workflows — автоматизации репозитория, в которых задача описывается на естественном языке в Markdown, а выполняется coding-агентом внутри GitHub Actions. На 3 октября 2026 года функция находится в public preview.

Для создания и запуска нужны включённые GitHub Actions, аккаунт с одним из AI-движков, а также установленный GitHub CLI и выполненная аутентификация.

Workflow состоит из двух частей:

• YAML frontmatter задаёт триггеры, разрешения, инструменты и допустимые операции записи;
• Markdown-текст описывает задачу для агента.

Markdown-файл компилируется в защищённый .lock.yml. В default branch нужно сохранить оба файла.

Поддерживаются GitHub Copilot, Anthropic Claude, OpenAI Codex и Google Gemini. Движок задаётся свойством engine; если оно отсутствует, используется GitHub Copilot. Для стороннего движка требуется его собственная аутентификация.

Ограничения безопасности

• репозиторий доступен только для чтения по умолчанию;
• запись выполняется через объявленные safe-outputs;
• секреты остаются вне среды агента;
• предлагаемые операции проходят проверку угроз;
• агент запускается в изолированной среде с сетевыми ограничениями.

Пример ежедневного отчёта:

---
on: daily # Ежедневный запуск.
permissions:
  contents: read # Чтение содержимого репозитория.
  issues: read # Чтение issues.
  pull-requests: read # Чтение pull requests.
  copilot-requests: write # Разрешение на запросы к GitHub Copilot.
network: defaults # Сетевой режим workflow.
tools:
  github:
    toolsets: [default] # Стандартный набор GitHub-инструментов.
safe-outputs:
  create-issue: # Разрешённое создание issue.
---

# Daily Repo Status Report

Review activity from the last 24 hours and create a concise issue with completed work, blockers, open questions, and recommended next steps.

Стоимость запуска складывается из минут GitHub Actions и расходов выбранного AI-движка. Для Agentic Workflows используется показатель AI Credits: 1 AIC равен $0.01. В frontmatter можно задать max-ai-credits; значение по умолчанию составляет 1000 AIC на запуск. Официальное описание Agentic Workflows объясняет учёт расхода. Команды gh aw logs и gh aw audit RUN-ID показывают длительность, токены и оценочную стоимость, но итоговые списания следует сверять с биллингом провайдера.

Полезные сценарии

Агент берёт подготовленную задачу

Задача: передать coding-агенту issue без потери контекста.

Исходные данные: issue со статусом Todo, критериями приёмки и меткой agent-task.

Действия: выбранный исполнитель или настроенная интеграция получает issue, меняет статус на In Progress, создаёт ветку и открывает связанный pull request. Одного присвоения поля Executor для запуска недостаточно.

Проверяемый результат: в проекте видна активная задача, а pull request содержит ссылку на исходный issue.

Ограничение: Project сам по себе не гарантирует запуск внешнего агента. Нужен отдельный исполнитель или интеграция.

Человек видит очередь на ревью

Задача: не пропускать pull requests, созданные агентами.

Исходные данные: представление Human Review с фильтром по полю Status со значением In Review.

Действия: интеграция переводит элемент в In Review после создания pull request; человек проверяет код и тесты.

Проверяемый результат: ожидающие решения элементы находятся в одном представлении; после принятия результата нужный элемент получает согласованный конечный статус.

Ограничение: автоматический статус не подтверждает качество реализации. Решение о merge остаётся отдельным этапом.

Агент готовит регулярный отчёт

Задача: собрать изменения, блокеры и следующие действия без ручного просмотра всего репозитория.

Исходные данные: Agentic Workflow с правами чтения issues и pull requests и безопасным выходом create-issue.

Действия: workflow запускается по расписанию, анализирует активность и создаёт отчётный issue.

Проверяемый результат: появился issue с заданным содержанием; в логах видны завершённый запуск, расход токенов и оценка AIC.

Ограничение: вывод агента может содержать неточности, поэтому отчёт следует использовать как материал для проверки, а не как окончательный источник данных.

Проверка результата

После настройки проведите один сквозной тест:

1. Создайте тестовый issue с меткой, по которой он должен попасть в проект.
2. Убедитесь, что элемент появился и получил начальный статус.
3. Переведите его в In Progress.
4. Откройте связанный pull request.
5. Примите либо закройте pull request в своём тестовом репозитории по его правилам. Учтите, что закрытие без слияния не означает выполнение исходной задачи.
6. Проверьте статус именно элемента PR и отдельно связанной issue: событие и фильтр workflow должны соответствовать вашей настройке. Не считайте переход PR в Done доказательством принятия всей задачи.
7. Убедитесь, что элемент появился в нужных представлениях и не был преждевременно архивирован.
8. Для API-автоматизации проверьте ответ GraphQL и новое значение поля в интерфейсе.
9. Для Agentic Workflow изучите gh aw logs; для отдельного запуска используйте gh aw audit RUN-ID.

Если шаг не сработал, сначала проверьте фильтр автоматического добавления, состояние workflow, ID поля и варианта, права токена и связь pull request с issue.

Типичные ошибки

• Issue без критериев приёмки. Агенту непонятно, какой результат считать завершённым.
• Слишком крупная задача. Разбивайте изменение так, чтобы один issue приводил к одному проверяемому pull request.
• Нет связи issue с pull request. Состояние проекта и история кода расходятся.
• Автоматический merge без человеческого контроля. Агентный результат требует проверки кода, тестов и последствий изменения.
• Одинаковые поля на двух уровнях. Issue Field и поле проекта с одним названием могут хранить разные значения.
• Попытка изменить системное поле через Projects API. Assignees и Labels обновляются на issue или pull request, а не на элементе проекта.
• Секреты в issue или workflow. Используйте GitHub Actions Secrets и минимальные разрешения.
• Непроверенный preview в критичном процессе. Agentic Workflows могут измениться; сохраняйте наблюдаемую проверку результата и возможность ручного запуска.

Официальные источники

• GitHub Projects
• Встроенные автоматизации Projects
• Управление Issue Fields в организации
• Projects GraphQL API
• GitHub Agentic Workflows

Следующий шаг

AGENTS.md / SESSION_NOTES — проектная память для coding-агентов

Если вы выстраиваете процесс постановки, выполнения и проверки задач AI-агентов, можно отдельно разобрать структуру проекта, права автоматизаций и контроль результата.

Если захотите обсудить, как это применить у себя или в команде — пишите в Telegram @pimenov