Run the Full Cycle with Copilot CLI
In this tutorial, we will wire Sortie to GitHub Issues and the Copilot CLI, clone a repository, let the agent write and commit code, push the result to a branch, and move the issue to review. The entire stack is GitHub-native. No Jira, no Claude Code, no Anthropic API key.
The GitHub integration tutorial proved that Sortie can talk to your issue tracker. This tutorial adds three new pieces: a real agent (Copilot CLI), workspace hooks for git operations, and a prompt template that guides the agent through the task.
If you already have a Sortie configuration for Copilot CLI that you want to update, see how to run Copilot CLI in ACP mode instead.
Prerequisites
GitHub integration tutorial completed: Sortie connects to your GitHub repository and
SORTIE_GITHUB_TOKENis setCopilot CLI installed on your machine, with the
copilotbinary on yourPATH:npm install -g @github/copilot copilot --versionYou should see a version string. If the command is not found, see the Copilot CLI installation guide.
GitHub authentication for Copilot CLI. The CLI resolves its own credential: a login it stored on the machine, or a token in
COPILOT_GITHUB_TOKEN,GH_TOKEN, orGITHUB_TOKEN. Sortie confirms that credential actually works before it starts work on an issue, rather than only checking that a variable is set; see authentication: one token, two jobs. If you have signed in to Copilot CLI on this machine, you are set. Otherwise export a token. Copilot CLI accepts a fine-grained personal access token with the Copilot Requests permission, and rejects a classic token (ghp_), which is what the GitHub integration tutorial has you create. To reuse the tracker token for both jobs, it has to be a fine-grained one; with a classic tracker token, sign in to Copilot CLI instead or export a separate fine-grained token. The environment reference has the details. Reusing a fine-grained tracker token looks like this:export GITHUB_TOKEN="$SORTIE_GITHUB_TOKEN"A git repository on GitHub that you can push to, with SSH or HTTPS credentials configured:
git ls-remote git@github.com:yourorg/yourrepo.git HEADYou should see a commit hash. If you get a permission error, fix your SSH or token setup before continuing.
No ANTHROPIC_API_KEY needed. That is the key difference from the Claude Code end-to-end tutorial: Copilot CLI authenticates through GitHub tokens, and a single token can serve both the tracker and the agent.
Create a GitHub issue
Create an issue with the backlog label. Pick a task that is concrete and verifiable. The agent reads the description as its primary instruction.
gh issue create --repo yourorg/yourrepo \
--title "Create a health check endpoint" \
--body "Add a /healthz endpoint that returns HTTP 200 with {\"status\": \"ok\"}. Create the handler file and a basic test." \
--label backlogNote the issue number in the output (e.g., #5). We will see it in the logs later.
Keep the backlog label on this issue: without an active_states label, Sortie never dispatches it, however well the task is written.
Vague descriptions like “improve the API” produce vague results. Concrete tasks (add a file, fix a specific bug, write a test) work best with any coding agent.
Set up the project directory
Create a directory for this tutorial, separate from the GitHub integration work:
mkdir sortie-github-e2e && cd sortie-github-e2eWrite the workflow file
Create WORKFLOW.md with the full configuration. Replace yourorg/yourrepo with your actual repository:
---
tracker:
kind: github
api_key: $SORTIE_GITHUB_TOKEN
project: yourorg/yourrepo
active_states:
- backlog
- in-progress
handoff_state: review
terminal_states:
- done
polling:
interval_ms: 30000
workspace:
root: ./workspaces
hooks:
after_create: |
git clone --depth 1 git@github.com:yourorg/yourrepo.git .
before_run: |
git fetch origin main
git checkout -B "sortie/${SORTIE_ISSUE_IDENTIFIER}" origin/main
after_run: |
git add -A
git diff --cached --quiet || \
git commit -m "sortie(${SORTIE_ISSUE_IDENTIFIER}): automated changes"
git push origin "sortie/${SORTIE_ISSUE_IDENTIFIER}" --force-with-lease
timeout_ms: 120000
agent:
kind: agent-client-protocol
command: copilot --acp --allow-all --model gpt-4.1
max_turns: 3
turn_timeout_ms: 1800000
max_concurrent_agents: 1
---
You are a senior engineer working in this repository.
## Task
**#{{ .issue.identifier }}**: {{ .issue.title }}
{{ if .issue.description }}
### Description
{{ .issue.description }}
{{ end }}
{{ if .issue.url }}
**Ticket:** {{ .issue.url }}
{{ end }}
## Rules
1. Read existing code before writing anything new.
2. Keep changes minimal. Implement exactly what the task requires.
3. Run any available lint and test commands before finishing.
{{ if not .run.is_continuation }}
## First run
Start by understanding the codebase structure. Check for existing patterns
(routing setup, test conventions) and follow them. Write the implementation,
add a test, and verify everything passes.
{{ end }}
{{ if .run.is_continuation }}
## Continuation (turn {{ .run.turn_number }}/{{ .run.max_turns }})
You are resuming. Run `git status` and check test output to understand the
current state. Continue from where the previous turn left off.
{{ end }}
{{ if and .attempt (not .run.is_continuation) }}
## Retry (attempt {{ .attempt }})
A previous attempt failed. Review workspace state and error output before
making changes. Do not repeat the same approach that failed.
{{ end }}If you followed the Claude Code end-to-end tutorial, this file will look familiar. The hooks and prompt template are nearly identical. The differences are in the tracker and agent configuration.
Tracker: GitHub instead of Jira
tracker.kind: github uses the GitHub adapter. The project field takes owner/repo format, and api_key: $SORTIE_GITHUB_TOKEN is a single Bearer token, with no email:token format like Jira. State is managed through labels: when Sortie transitions an issue, it removes the old state label, adds the new one, and closes the issue if the target state is terminal. No Jira workflow configuration required.
Agent: Copilot CLI in ACP mode
agent.kind: agent-client-protocol tells Sortie to launch whatever agent.command names, keep that process alive for the whole session, and send each turn to it. The kind has no default binary and no model or permission settings of its own, so the runtime and its options live in one string:
Part of agent.command | Effect |
|---|---|
copilot | The Copilot CLI binary, found on your PATH at session start. |
--acp | Starts Copilot CLI in ACP mode, the protocol interface Sortie drives, instead of its interactive chat. |
--allow-all | Approves every tool request. Without an approval switch, Copilot CLI asks before each tool call, Sortie refuses because an unattended run has nobody to answer, and the turn ends. |
--model gpt-4.1 | Selects the model. Replace it with your preferred model, or drop the switch to use your account’s default. |
Where the Claude Code tutorial sets permission_mode: bypassPermissions, this route carries the same decision in the command. With --allow-all, Copilot CLI runs any tool the model picks, its shell included, with your user account’s permissions, and nobody reviews the call first. Point this first run at a repository you can afford to lose, and put the agent in a hardened sandbox before you use this setup for real work. The Copilot CLI reference covers narrower postures.
agent.max_turns: 3 caps the Sortie turns in a session, and agent.turn_timeout_ms: 1800000 gives each turn 30 minutes.
Authentication: one token, two jobs
SORTIE_GITHUB_TOKEN authenticates Sortie to the GitHub API. GITHUB_TOKEN (or GH_TOKEN, or COPILOT_GITHUB_TOKEN) authenticates Copilot CLI to GitHub’s AI backend. They can be the same token when it is a fine-grained one, as the prerequisites explain. If you ran the export GITHUB_TOKEN="$SORTIE_GITHUB_TOKEN" command from the prerequisites, both are already set.
Before it starts work on an issue, Sortie opens a short-lived session of its own and sends one request through Copilot CLI to confirm the credential actually answers, rather than only checking that a variable is set. A missing or rejected credential stops the run immediately with Copilot CLI’s own message about it, instead of failing partway through the first turn. See credential verification for the mechanism every agent kind shares.
Workspace and hooks
The hooks work the same way as in the Claude Code tutorial: after_create clones the repo, before_run creates a branch from origin/main, and after_run commits and pushes. For a detailed walkthrough of the hook lifecycle and environment variables, see the hooks section in the Claude Code tutorial.
Prompt template
The template body is a Go text/template rendered per issue. It branches on three conditions: first run, continuation, and retry. The #{{ .issue.identifier }} prefix uses the # convention because GitHub Issues are referenced as #5, not PROJ-55.
Validate the configuration
Check for syntax errors before running:
sortie validate ./WORKFLOW.mdNo output means no errors. Confirm with:
echo $?This should print 0.
Run Sortie
Start Sortie:
sortie ./WORKFLOW.mdYou should see output similar to this (timestamps and IDs will differ, and the tick completed lines carry more fields than shown here):
level=INFO msg="sortie starting" version=0.x.x workflow_path=/home/you/sortie-github-e2e/WORKFLOW.md
level=INFO msg="database path resolved" db_path=/home/you/sortie-github-e2e/.sortie.db
level=INFO msg="http server listening" addr=127.0.0.1:7678
level=INFO msg="sortie started"
level=INFO msg="tick completed" candidates=1 dispatched=1 ... running=1 retrying=0 ...
level=INFO msg="running hook" issue_id=5 issue_identifier=5 hook=after_create workspace=…/workspaces/5
level=INFO msg="running hook" issue_id=5 issue_identifier=5 hook=before_run workspace=…/workspaces/5
level=INFO msg="workspace prepared" issue_id=5 issue_identifier=5 workspace=…/workspaces/5
level=INFO msg="agent credential verified" issue_id=5 issue_identifier=5 duration_ms=…
level=INFO msg="agent session started" issue_id=5 issue_identifier=5 session_id=…
level=INFO msg="turn started" issue_id=5 issue_identifier=5 turn_number=1 max_turns=3The agent credential verified line is Sortie proving your GitHub token works, in a short-lived session of its own, before it starts the working session below it. The agent is now working. A Copilot CLI session typically takes 3–10 minutes depending on the task complexity and model. The agent reads files, writes code, and runs tests. Each action appears as events in the log at debug level.
Notice that issue identifiers are bare numbers (5, not #5 or PROJ-55). The GitHub adapter uses the issue number for both the issue ID and the issue identifier.
When the agent finishes, you will see:
level=INFO msg="turn completed" issue_id=5 issue_identifier=5 turn_number=1 max_turns=3
level=INFO msg="running hook" issue_id=5 issue_identifier=5 hook=after_run workspace=…/workspaces/5
level=INFO msg="worker exiting" issue_id=5 issue_identifier=5 exit_kind=normal turns_completed=1
level=INFO msg="handoff transition succeeded, releasing claim" issue_id=5 issue_identifier=5 handoff_state=review
level=INFO msg="tick completed" candidates=0 dispatched=0 ... running=0 retrying=0 ...Here is the full lifecycle, step by step:
- Sortie polled GitHub and found issue #5 with a
backloglabel. after_createcloned the repository intoworkspaces/5/.before_runcreated the branchsortie/5fromorigin/main.- Sortie verified the credential in a session of its own, then Copilot CLI started the working session and worked on the task.
- The agent completed the turn and exited.
after_runcommitted the changes and pushed the branch.- Sortie removed the
backloglabel and addedreview, leaving the issue open for a human. - The next poll found zero candidates and went idle.
Press Ctrl+C to stop Sortie.
Verify the results
Three things should be visible now: the code in the workspace, the branch on the remote, and the issue state in GitHub.
Check the workspace
Look at the git log in the workspace directory:
cd workspaces/5
git log --oneline -5You should see the agent’s commit at the top:
a1b2c3d sortie(5): automated changes
f4e5d6c (origin/main) Initial commitCheck what the agent produced:
git diff HEAD~1 --statThis shows the files the agent created or modified.
Check the remote branch
Back in any directory, verify the branch exists on your remote:
git ls-remote git@github.com:yourorg/yourrepo.git "refs/heads/sortie/5"You should see a commit hash. The sortie/5 branch is on GitHub, ready for a pull request.
Check GitHub
Open the issue in the browser, or check from the command line:
gh issue view 5 --repo yourorg/yourrepoVerify three things: the issue is still open, the backlog label is gone, and the review label is present. Handoff parks the issue for a human rather than finishing it, so closing it is a call you make after reading the branch.
If the label did not change: review the Sortie logs for error messages and confirm your token has repo scope.
Check the dashboard
Open http://127.0.0.1:7678/ in a browser while Sortie is running. Overview lists issue 5 under Ended today with the ending “review”, which matches the label you just checked. Its completed run, with turns, duration, and status, is on History.
What we built
We ran the complete Sortie lifecycle with Copilot CLI on GitHub Issues, entirely GitHub-native. One token authenticates both the tracker and the agent. Sortie polled GitHub, cloned the repository, launched Copilot CLI in ACP mode, let it write and test code, pushed the result to a branch, and moved the issue to review.
The same orchestration loop powers the Claude Code end-to-end tutorial and the Codex end-to-end tutorial with different agents and trackers. Sortie’s adapter-agnostic design means swapping the agent is a config change. The prompt template, hooks, and overall flow carry over.
Where to go next:
- Write a prompt template: conditionals, iteration, and template functions for production prompts
- WORKFLOW.md configuration reference: every field, every default, every constraint
- Monitor with Prometheus: token usage, session counts, and retry rates as time-series metrics
- Copilot CLI on the Agent Client Protocol: launch switches, credentials, permission posture, and limitations
- GitHub adapter reference: field mapping, state derivation, and rate limiting
- Scale agents with SSH: remote execution for production workloads
Was this page helpful?