Docs › Agent › Remote agents in GitHub Actions
Remote agents in GitHub Actions
Run an agent in your repository's GitHub Actions instead of on your machine, and get its work back as a pull request.
On this page
An agent can run off your machine: in your repository's GitHub Actions, on a branch of its own, coming back as a pull request. Its card in the chat follows it step by step, as a local agent's does, and the agent that started it is told when it finishes, with the report and the link.
Set a repository up
- Run AstraCode: Enable remote agents for this repository from the command palette. It writes
.github/workflows/astracode-agent.ymland shows it as a diff. - Review it and commit it to the default branch yourself: AstraCode never commits or pushes it.
- In the repository's settings on GitHub, under Actions, General, allow GitHub Actions to create pull requests, so the run can open one.
No secret is needed. Each run signs in with the identity token GitHub gives the job (the workflow asks for id-token: write), and AstraCode accepts it only for a run you started for that repository, and only until the run ends. A repository that already has an ASTRACODE_TOKEN Actions secret (an API key with the Run agents scope) keeps using it.
Start one
Ask for it ("do this in a remote agent"), or give an agent definition isolation: remote. Before anything starts, a dialog shows the repository, the branch it starts from, the new branch astracode/<run id> and the prompt, every time and in every approval setting, because it starts a job on your repository. The first time, the editor asks you to sign in to GitHub with the repo and workflow scopes.
The agent starts from your current branch if GitHub has it, otherwise from the default branch, and the dialog says which. Commits you have not pushed and uncommitted changes are not sent. A definition's timeoutMinutes (1 to 360, default 60) stops a run that goes on too long. Custom agents are sent with their prompt, tools and model; hooks, connectors and memory belong to your machine and are not.
While it runs
The card shows its steps and the tool it used last, refreshed every ten seconds, and it is listed in the Tasks panel as rm1, rm2 and so on. Stop cancels the workflow run. When it ends, Open PR opens the pull request, Check out branch fetches its branch and switches to it, and View run opens the run on GitHub. The report is also in the run's job summary.
What it can do there
The workflow runs the AstraCode CLI at a pinned version with --permissions auto: it edits and runs commands, and is refused what the editor confirms even with Never ask. The checkout keeps no GitHub token, so the agent cannot push; the workflow's own last step commits its changes to astracode/<run id>, pushes that branch alone and opens the pull request (a draft when the agent did not finish). Third-party actions are pinned to commit SHAs, and every input is checked before anything runs.
Usage
The run uses the allowance of whoever started it, like their own runs in the editor; with an ASTRACODE_TOKEN secret, that key's. The Actions minutes are your repository's own. Progress events (step numbers, tool names, the report, the pull request link) are kept by AstraCode for seven days and can be read only by you and the key that wrote them. Plans are on the pricing page.
If something goes wrong
- The run cannot open a pull request: allow GitHub Actions to create pull requests in the repository's settings.
- The workflow is not found: commit
.github/workflows/astracode-agent.ymlto the default branch. - Open the run with View run to read its log on GitHub, and see CLI problems.
← Subagents and background tasks Infrastructure as code →
All documentation
Get started
Using the editor
- Tab completion
- Edit and ask about a selection
- Reviewing the agent's changes
- Git: commit messages, branch review and conflicts
- Dictation
- Layout, themes and the settings page
Agent
- Agent overview
- Agent, Plan, Ask and Debug
- Approvals and permissions
- Plan mode
- Debug mode
- Tools
- Browser tools
- How the agent checks its work
- Checkpoints and undo
- Running several agents at once
- Subagents and background tasks
- Remote agents in GitHub Actions
- Infrastructure as code
Context
Workspaces
Connectors
- Connectors (MCP servers)
- Connector configuration reference
- Use AstraCode from Claude, ChatGPT and other apps
Extending AstraCode
CLI
Account and usage
- Usage and limits
- Bring your own key
- What AstraCode sends and keeps
- Reporting a problem and getting help
Troubleshooting
- Troubleshooting
- Sign-in problems
- Install and update problems
- Chat panel problems
- Agent run problems
- Connector problems
- Dictation problems
- Usage, billing and network errors
- CLI problems