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

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

Содержание

1. Как GitHub Projects помогает управлять агентами
2. Поля и представления проекта
3. Настройка рабочего процесса
4. Встроенные автоматизации
5. Автоматизация через API и Actions
6. GitHub Agentic Workflows
7. Полезные сценарии
8. Проверка результата
9. Типичные ошибки

Как 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 там не отображаются.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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.

Добавить элемент и изменить его поле в одном GraphQL-вызове нельзя.

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

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. На 7 сентября 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 на запуск. Команды gh aw logs и gh aw audit RUN-ID показывают длительность, токены и оценочную стоимость, но итоговые списания следует сверять с биллингом провайдера.

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

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

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

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

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

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

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

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

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

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

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

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

Ограничение: автоматический статус не подтверждает качество реализации. Решение о 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. Проверьте, что встроенный workflow установил 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-агентов

Связанные материалы

• База знаний: ClawPatch — семантический код-ревью на базе ИИ-агентов
• База знаний: Composio — интеграционная платформа для AI-агентов

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

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