--- title: "Your agents live in GitHub. Now they can ship to Guild." canonical: "https://www.guild.ai/blog/product/guild-github-agents" --- # Your agents live in GitHub. Now they can ship to Guild. - **Category:** Product - **Author:** Howard Cheng - **Published:** Oct 27, 2026 - **Reading time:** 5 min **An agent starts as something one person builds. Soon, it is something a team depends on.** That is when the questions change. Who owns it? Which version is running? What can it access? Where do you look when a run goes wrong? An agent can be useful long before the organization has good answers. ![](https://images.prismic.io/guild-ai/pVNOlYeJ5Hjlipuo_Screenshot2026-10-27at3.40.30PM.png?auto=format,compress) Source stays in your repository. The release workflow sends the selected agent files to Guild. Developers already have a way to collaborate on the source: GitHub, pull requests and tests. Getting that source into a shared runtime should fit the same workflow. A prompt change can change production behavior, and releasing it deserves the same care as releasing code. The [Publish Agent to Guild GitHub Action](https://github.com/marketplace/actions/publish-agent-to-guild) closes that gap. Point it at an agent directory and a target in Guild. It uploads the source, waits for validation and publishes a version. You decide whether that happens manually, after a merge or when you publish a GitHub Release. **Want to try it in your repository?** Copy the setup prompt below and paste it into Claude Code, Codex or your preferred coding agent. It can inspect your agent folders and prepare the release workflow for you to review. ## The agent already has a home Once two people work on an agent, the problem changes. They need to review a prompt together, test a tool change, and know which version their colleagues are running. Copying files between an editor and a repository becomes another release step to remember. We ran into this ourselves as more engineers started collaborating on shared agents. GitHub was where we wanted to review changes. Guild was where we wanted to run them. Asking developers to maintain a separate source workflow between the two added friction without improving the agent. With the GitHub Action, your repository can be the authoring source of truth. Guild holds the published versions and provides the environment in which they run. The handoff is an explicit release, using the source you chose to ship. That gives the next person who maintains the agent a familiar starting point: a reviewed change in the repository, a version in Guild, and a place to inspect what happens when it runs. ## A directory becomes a version The implementation follows the path developers can already use from a terminal. The GitHub Action installs a pinned Guild CLI and calls guild agent save --publish. The CLI sends the files through Guild’s API, using the platform’s existing validation and publication process. ![](https://images.prismic.io/guild-ai/xrl03nalLCFTlkHP_Screenshot2026-10-27at3.40.30PM.png?auto=format,compress) Publishing produces a version. Workspace installation and runtime testing are separate steps; workspace update settings determine when an installed agent adopts a newer version. You do not need to clone a Guild agent first, add guild.json, or create the target by hand. With explicit creation enabled, the first release can create a private agent and publish version 1.0.0. Your repository can stay private. GitHub checks out the source in your workflow, and the workflow sends the selected files to Guild. Guild does not need a GitHub App installation or permission to read the repository. ## Set up your first release in three steps You need a Guild account, a supported agent package in your repository, and permission to add a workflow and an Actions secret. Your organization must allow the GitHub Action to run. Start with a manual release so you can verify the result before automating it. ## 1. Have your coding agent prepare the workflow Open your repository in Claude Code, Codex or another coding agent. Copy this prompt and paste it into that session. It asks the coding agent to check the package, confirm the destination and prepare a workflow. [Setup prompt: see Appendix A, or copy it from the online article.](https://legendary-adventure-o7jj1ql.pages.github.io/howard/apps/agent-publishing-blog/#setup-helper) The button copies instructions; it does not install anything or grant access. Prefer to configure it yourself? Follow the [complete setup guide](https://docs.guild.ai/cli/github-actions). ## 2. Connect the publishing key In [Guild](https://app.guild.ai/), use the account switcher to select the personal account or organization that will own the agent. Open [**Access & Setup**](https://app.guild.ai/organizations/guildai/settings/api-keys) → **API keys**, create a key named something like **GitHub publishing**, and grant **Agents: Read & write**. Leave other permissions off unless the package needs them, such as **Skills: Read** for private skills. Ask your Guild account admin if you cannot create keys. The shortcut above opens the Guild organization. Switch to your own account or organization before creating the key. Look for the settings icon; its “Access & Setup” label appears on hover. Copy the full id:secret value when Guild shows it. In your GitHub repository, open **Settings → Secrets and variables → Actions → New repository secret**. Name it GUILD\_API\_KEY, paste the value and save. Keep the value out of your source files and coding-agent conversation. The [API-key guide](https://docs.guild.ai/platform/api-keys) covers rotation and revocation. This key can write all agents in its Guild account. The destination, such as myorg~hello, must use that account’s URL name. GitHub Actions uses the API key; your browser login is not used by the release job. ## 3. Release it, then run it on Guild Review the generated workflow and merge it onto your default branch. Open **Actions → Publish agent → Run workflow**, choose that branch and run the release. In Guild, find the agent in the account you selected and confirm its published version. To use it, add the agent to a test workspace in Guild, configure any required integrations and credentials, then run a representative task. After the first successful run, change the agent in a pull request and release the next version. You can then enable releases on merge if that suits your team. If validation fails, the workflow fails and the previously published version stays in place. The CLI respects repository and nested .gitignore rules, and excludes local configuration such as .env\* and .npmrc. Pass the publishing key only to trusted release steps and keep it away from unreviewed pull-request code. ## You own the release policy The GitHub Action supplies the publish operation. Your workflow decides when to call it. Use a manual trigger while testing, a push to your main branch for releases after merge, or a GitHub Release event for a deliberate release cadence. Keep your existing tests and review requirements around that choice. A repository can contain several agents. Each publish step maps one directory to one Guild target. Repeat the step for additional agents, or use a matrix for independent releases. When order matters, publish sequentially. Those publications succeed or fail individually. This is one-way publishing. Guild editor changes do not become GitHub commits. If repository source should replace those changes, opt in with overwrite: 'true'. Otherwise, conflicting saves stop for review. Published version numbers cannot be reused, and releasing a version does not make an agent public. ## The runtime is where governance matters Reviewing source is useful. Operating the resulting agent brings another set of questions: which credentials can it use, which tools may it call, and what happened during a particular run? In [When a Skill Becomes a Shadow Agent](https://www.guild.ai/blog/engineering/when-a-skill-becomes-a-shadow-agent), I wrote about the point at which portable instructions acquire operational consequences. That same boundary matters here. A repository gives people a place to collaborate; an execution platform gives the organization a place to apply controls to the work. When agents run on Guild, they use the runtime and control plane already responsible for identity, credential policies, governed model and tool access, and session visibility. Teams can inspect runs and understand usage and spend in the same platform where they operate the agent. A release makes a new version available; the account and workspace configuration determine how it operates. The publishing API key authorizes saving and publishing agent versions. Runtime credentials and tool permissions are configured in Guild for the agent’s work. Keeping those responsibilities explicit makes a release easier to reason about: shipping a new prompt is not a request to grant new access. This also connects to Guild’s [MCP Gateway](https://www.guild.ai/product/mcp-gateway), which brokers access to tools and integrations under centrally managed policies and credentials. The GitHub Action handles how source reaches Guild. The runtime and gateway handle the agent’s execution and governed connections. Teams can reuse those controls as they bring more agents onto the platform. ## Meet the agent where it is Guild supports several agent types, including its TypeScript SDK, Goose, OpenClaw and LangGraph. Publishing follows the same directory-to-target pattern while each type retains its own package and runtime requirements. A team should be able to choose a framework for the task and still share a release process. That is our framework-neutral direction in practical terms. The publishing layer moves a package; the appropriate runtime executes it. It does not translate arbitrary frameworks or supply every dependency an agent used on a developer’s machine. Required skills, integrations and external services still need to be configured. That distinction came up repeatedly while testing real repositories. An agent can depend on more than its recipe: a tool server, a reference file, or application code that supplies context. Preserving the customer’s intended behavior means checking those dependencies rather than treating a successful upload as the end of the job. **GitHub is one way to ship.** You can also publish a directory with the CLI from another CI system, or sign in locally with guild auth login and publish interactively. GitHub Actions uses an account API key; local publishing can use browser OAuth. Both reach the same Guild publication path. We plan to extend this publishing experience to more source hosts, including **GitLab and Bitbucket**. The CLI already provides a common path for other CI systems; making setup just as straightforward across those hosts is the next direction. The GitHub Action is available today. The latest generation of AI tooling has made it much easier to build an agent. The lasting work is making it something a team can own, maintain and trust. This release path gives teams a practical way to bring the agents they already build into the system where they can operate them. ## Try your first release Bring this article to the repository where your agent lives. Copy the setup prompt, have your coding agent prepare the workflow, and follow the three steps above to publish and run your first version on Guild. The GitHub Action is public and open source under Apache 2.0. [Get the GitHub Action](https://github.com/marketplace/actions/publish-agent-to-guild) [Read the complete setup guide](https://docs.guild.ai/cli/github-actions) Related reading: [The Guild API is now public](https://www.guild.ai/blog/engineering/guild-api-announcement) · [Bring Your Own Agents](https://www.guild.ai/blog/engineering/bring-your-own-agents-openclaw-langchain) · [GitHub Action source and feedback](https://github.com/guildaidev/publish-agent-action) ## Appendix A: Read or manually copy the setup prompt Paste this into a coding agent that has access to your repository. Set up agent publishing from this repository to Guild using the official GitHub Action: https://github.com/marketplace/actions/publish-agent-to-guild Read the complete setup guide first: https://docs.guild.ai/cli/github-actions Inspect the agent directories, formats and dependencies. Propose which folder maps to which Guild owner~name target and agent type. Report unsupported fields or missing dependencies without silently changing agent behavior. Start with one manual workflow named "Publish agent" using workflow\_dispatch and guildaidev/publish-agent-action@v1.0.0. Include checkout without persisted credentials, contents: read, an Ubuntu runner, and concurrency for the target. Use version 1.0.0 only for a new target; otherwise choose a higher version than the one already published. Ask me to confirm the target, private creation and any overwrite of Guild editor changes. Keep publishing credentials out of pull\_request and pull\_request\_target jobs. Walk me through creating a Guild account API key with Agents: Read & write and storing the full id:secret value as the GUILD\_API\_KEY repository Actions secret. Explain any additional permissions required for private dependencies. Never ask me to paste the key into chat, read it back, print it or commit it. Validate the workflow and show the diff for review. Do not merge or publish until I approve. After an approved release, verify the agent and version in Guild, then help me add it to a test workspace, configure its required tools and credentials, and run a representative task. Report publication and runtime results separately. Once that works, ask whether I want releases on merge or on a GitHub Release. ## Appendix B: What the GitHub Action step looks like The setup prompt prepares the surrounding workflow too. At its core, each publish step maps one source directory to one agent: - name: Publish agent to Guild uses: guildaidev/publish-agent-action@v1.0.0 with: path: agents/hello agent: myorg~hello version: '1.0.0' create-if-missing: 'true' agent-type: GOOSE env: GUILD\_API\_KEY: ${{ secrets.GUILD\_API\_KEY }} Replace the path and target with your own. The key’s account must own the target. Use a trusted release job on an Ubuntu runner, with checkout and concurrency configured as shown in the [complete setup guide](https://docs.guild.ai/cli/github-actions). ## Appendix C: Prefer to try the CLI locally first? For a supported Goose package at ./agents/hello, run this in a Bash terminal. Replace myorg~hello with your target. This uses browser OAuth and publishes immediately after you complete login. npm install --global @guildai/cli@0.27.2 unset GUILD\_API\_KEY guild auth login guild auth status guild agent save myorg~hello --path ./agents/hello \\ --create-if-missing --agent-type GOOSE \\ --version-number 1.0.0 --no-bump --publish Use 1.0.0 for a new agent and a higher version for an existing one. Check the account reported by guild auth status before the save command. Local publishing exercises the same upload and validation path; it does not install a GitHub workflow.