GitHub 에이전트 워크플로 만들기

참고

GitHub 에이전트형 워크플로 are in 공개 미리 보기 and subject to change.

만들기에 대하여 GitHub 에이전트형 워크플로

GitHub 에이전트형 워크플로를 코딩 에이전트로 만들거나(권장) 수동으로 만들 수 있습니다. 워크플로는 .github/workflows/에 있는 Markdown 파일로, 구성 정보용 YAML 프런트매터와 AI 에이전트용 자연어 지침을 포함하고 있습니다.

에이전트 워크플로를 만들려면 Markdown으로 워크플로를 정의하고, 이를 .lock.yml 파일로 컴파일한 다음 두 파일을 모두 커밋한 후, GitHub Actions 트리거 또는 GitHub CLI로 실행합니다.

이 문서에서는 워크플로 만들기, 업데이트 및 재사용과 같은 핵심 작업에 중점을 둡니다. 전체 기술 세부 정보 및 추가 패턴은 설명서 사이트를 사용합니다GitHub 에이전트형 워크플로.

Prerequisites

시작하기 전에 다음을 확인합니다.

AI 계정: GitHub Copilot, Anthropic Claude또는 OpenAI CodexGoogle Gemini
GitHub 쓰기 액세스 권한이 있는 리포지토리
GitHub Actions 리포지토리에 대해 활성화됨
GitHub CLI (gh) v2.0.0 이상 설치 및 인증

버전을 확인하려면 gh --version을(를) 실행합니다. 인증하려면 다음을 실행합니다.
```
gh auth login --scopes repo,workflow
```
GitHub 에이전트형 워크플로용으로 설치된 GitHub CLI 확장 프로그램:
```
gh extension install github/gh-aw
```
버전 2.90.0 이상을 사용하는 GitHub CLI 경우 아직 gh aw 설치되지 않은 경우 모든 명령을 실행하면 확장을 자동으로 설치하라는 메시지가 표시됩니다.

Authentication

선택한 AI 엔진(코딩 에이전트)을 사용하여 다음 두 가지 방법으로 인증을 설정할 수 있습니다.

조직 청구에 기본 제공 GITHUB_TOKEN 사용(권장). 이 옵션은 특히 GitHub Copilot 엔진용이며, GitHub Copilot 플랜을 사용하는 조직이 소유한 리포지토리에서만 사용할 수 있습니다.
개인 리포지토리 및 타사 AI 엔진에 API 키 사용 personal access token

기본 제공 `GITHUB_TOKEN` 사용

팁

조직 소유의 리포지토리에서 사용하는 GitHub Copilot 경우 이 섹션의 기본 제공 GITHUB_TOKEN 방법을 사용하는 것이 좋습니다.

조직 소유 리포지토리에서 GitHub Copilot를 사용 중인 경우, GitHub Actions 대신 personal access token의 기본 제공 GITHUB_TOKEN를 사용할 수 있습니다. 이렇게 하면 워크플로 사용량을 조직에 직접 청구하고 Copilot 요청에 대한 personal access token 비밀을 관리할 필요가 없습니다. 이 기능을 설정하려면:

조직 관리자는 아직 사용하도록 설정되지 않은 경우 Copilot 설정에서 "조직에 청구된 Copilot CLI 사용 허용" 정책을 사용하도록 설정해야 합니다.
조직에 청구하려는 워크플로의 경우 워크플로 프런트매터에 copilot-requests: write를 넣으세요permissions.

조직 청구 활성화

GitHub Copilot 정책 설정에서 "조직에 청구된 Copilot CLI 사용 허용"을 사용하도록 설정해야 합니다. "Copilot CLI" 정책을 이미 사용하도록 설정한 경우 청구 정책은 기본적으로 사용하도록 설정됩니다.

GitHub의 오른쪽 위 모서리에서 프로필 사진을 클릭한 다음, Your organizations를 클릭합니다.
조직을 클릭하여 선택합니다.
조직 이름에서 설정을 클릭합니다. "설정" 탭이 표시되지 않으면 드롭다운 메뉴를 선택한 다음 설정을 클릭합니다.
사이드바에서 Copilot 을 클릭한 다음, 정책을 클릭합니다.
"Copilot CLI"를 사용하도록 설정한 다음 , "조직에 청구된 Copilot CLI 사용 허용"을 사용하도록 설정합니다.

워크플로 비용을 조직에 청구하기

워크플로를 만들 때 워크플로 프런트매터에서 permissions 아래에 copilot-requests: write을 포함해야 합니다. 이 사용 권한을 설정하면 Copilot 요청에 GitHub Actions' 토큰이 사용되고 해당 요청에 대해 COPILOT_GITHUB_TOKEN 무시됩니다. GitHub Actions 토큰에 조직으로부터의 GitHub Copilot 액세스 권한이 없는 경우 워크플로는 Copilot 요청을 보낼 때 실패하고 대신 COPILOT_GITHUB_TOKEN 구성해야 합니다.

permissions:
  contents: read
  copilot-requests: write

personal access token 또는 API 키 사용

개인 리포지토리 또는 타사 AI 엔진의 경우 API 키를 저장하는 personal access token 리포지토리 비밀을 만들어야 합니다. GitHub Copilot의 경우 핵심은 세분화된 personal access token를 저장하는 COPILOT_GITHUB_TOKEN입니다.

gh aw add-wizard를 사용하는 경우 설정 흐름에서 해당 비밀을 생성하라는 메시지를 표시합니다. GitHub 웹 인터페이스에서 또는 수동으로 에이전트형 워크플로를 만드는 경우, 먼저 리포지토리의 GitHub Actions 시크릿에 시크릿을 직접 추가해야 하며, 이는 GitHub UI 또는 CLI에서 gh aw secrets set를 사용해 수행할 수 있습니다. 지침은 인증 참조를 참조하세요.

워크플로 만들기

에이전트 워크플로를 생성하는 권장 방법은 CLI 코딩 에이전트 또는 VS Code를 사용하는 것입니다. 이렇게 하면 워크플로 작성, 컴파일 및 커밋을 위한 하나의 안내 경로가 있습니다.

CLI 코딩 에이전트 또는 VS Code 사용

확장(GitHub CLI)을 GitHub 에이전트형 워크플로gh aw 사용하여 에이전트 작성을 위해 리포지토리를 초기화합니다(리포지토리의 처음 설치에 권장됨).
```
gh aw init
```
이렇게 하면 에이전트 워크플로 작성과 관련된 기술, 지침 및 사용자 지정 에이전트가 추가되므로 코딩 에이전트는 워크플로를 보다 효과적으로 만들고 편집할 수 있습니다.
리포지토리의 컨텍스트(예 코파일럿 CLI : VS Code 에이전트 모드)에서 코딩 에이전트를 시작합니다.

기술을 언급하고 agentic-workflows 원하는 워크플로를 설명하는 프롬프트를 입력합니다.

Copilot prompt

/agentic-workflows Create a new workflow that creates a daily report on
recent activity in the repository, delivered as
an issue.

/agentic-workflows Create a new workflow that creates a daily report on
recent activity in the repository, delivered as
an issue.

에이전트는 워크플로를 생성하고 GitHub CLI를 사용하여 워크플로를 컴파일합니다.
워크플로를 검토한 다음 에이전트에 파일을 커밋하고 푸시하도록 요청합니다.
GitHub Actions 탭에서 또는 GitHub CLI 실행으로 워크플로를 트리거합니다:
```
gh aw run YOUR-WORKFLOW-NAME
```

기타 생성 방법

에이전트 워크플로를 만들 수도 있습니다.

GitHub 웹 인터페이스에서. GitHub 웹 인터페이스에서 워크플로 만들기 참조하세요.
수동으로. 수동으로 편집하여 워크플로 만들기를 참조하세요.

워크플로 구조 참조

각 워크플로 markdown 파일에는 다음 두 부분으로 구성합니다.

섹션	Purpose
YAML 프런트매터	트리거(`on`), 권한, 안전한 출력 및 AI 엔진을 정의합니다.
Markdown 본문	AI 에이전트가 워크플로를 실행할 때 따르는 자연어 지침입니다.

주요 프런트매터 필드:

Field	Description
`on`
GitHub Actions 트리거와 동일한 구문을 사용하는 이벤트 트리거입니다.
`permissions`	에이전트에 부여된 리포지토리 권한 기본값은 `read-all`입니다.
`safe-outputs`	에이전트가 수행할 수 있는 쓰기 작업(예: `create-issue`, , add-comment``create-pull-request).
`engine`	사용할 AI 엔진(`copilot`이 기본값이며, `claude`, `codex`, `gemini`도 지원됨)

전체 프런트매터 참조는 frontmatter 설명서를 참조GitHub 에이전트형 워크플로하세요.

에이전트 워크플로 예제

다음 예제는 리포지토리에 대한 간소화된 주간 문제 활동 보고서입니다.

---
on: weekly on monday

permissions:
  issues: read
  copilot-requests: write

network: defaults

tools:
  github:
    toolsets: [issues]

safe-outputs:
  create-issue:

---

# Weekly issue activity report

Review issue activity from the last 7 days in this repository.

Create a GitHub issue that includes:

- Total issues opened and closed this week.
- The top recurring themes from issue titles and descriptions.
- A short list of notable issues that still need attention.
- Two or three actionable recommendations for maintainers.

Keep the report concise and action-oriented.

워크플로 업데이트

기존 워크플로를 업데이트하려면 다음을 수행합니다.

에서 워크플로 마크다운 파일을 편집합니다 .github/workflows/.
잠금 파일을 새로 고치려면 다시 컴파일합니다.
```
gh aw compile
```
업데이트된 파일을 모두 커밋하고 푸시합니다.
풀 리퀘스트를 열고 GitHub Actions 검증 상태를 확인합니다.

자세한 편집 지침은 워크플로 편집을 참조하세요.

워크플로 다시 사용

액세스할 수 있는 외부 리포지토리에서 워크플로를 가져올 수도 있습니다. 예를 들어 다음에서 githubnext/agentics워크플로를 추가할 수 있습니다.

gh aw add-wizard githubnext/agentics/daily-repo-status

비대화형 설정에서는 gh aw add를 사용할 수 있으며, 필요에 따라 버전을 고정할 수도 있습니다.

워크플로를 가져오면 GitHub CLI는 나중에 gh aw update로 업스트림에서 업데이트할 수 있도록 frontmatter에 source: 값을 저장합니다.

신뢰할 수 있는 원본에서만 워크플로를 가져오고 워크플로를 리포지토리에 추가하기 전에 워크플로가 수행하는 작업을 검토합니다. 표시된 private: true 워크플로는 다른 리포지토리로 가져올 수 없습니다.

가져온 워크플로 GitHub CLI 를 업데이트할 때 로컬 변경 내용을 유지하려고 합니다. 병합 충돌이 있는 경우 해결한 후 다시 실행 gh aw compile 합니다.

자세한 내용은 워크플로 재사용을 참조하세요.

다음 단계

워크플로 예제, 고급 패턴, 가이드 및 문제 해결 정보는 설명서 사이트를 참조GitHub 에이전트형 워크플로하세요.

이 기사에서