Skip to main content

Documentation Index

Fetch the complete documentation index at: https://allhandsai-docs-onboarding-agent-canvas.mintlify.app/llms.txt

Use this file to discover all available pages before exploring further.

Use the GitHub Repository Monitor when you want Agent Canvas to watch a repository and trigger an OpenHands agent when matching activity happens. Common examples include:
  • Monitoring new issues and pull requests
  • Watching failed CI runs
  • Checking for dependency or release activity
  • Creating follow-up work when a repository changes

​
Prerequisites

Before you start, make sure you have:
  • Agent Canvas installed and running
  • An LLM configured for the backend that will run the automation
  • Access to create a GitHub token for the repository you want to monitor
  • Access to install MCP servers and save secrets in Agent Canvas
If you are new to Agent Canvas, start with Install and First-Time Setup.

​
Create a GitHub Access Token

  1. Go to GitHub Developer Settings.
  2. Click Generate new token.
  3. Prefer a fine-grained personal access token if your organization supports it.
  4. Give the token a clear name, such as Agent Canvas Repo Monitor.
  5. Select repository access:
    • Choose Only select repositories for the safest setup.
    • Choose All repositories only if the automation needs broad access.
  6. Set an expiration date that matches your team’s security policy.

​
Add Repository Permissions

In the token setup screen, grant only the permissions your monitor needs. For most repository monitors, start with:
PermissionAccess
ContentsRead-only, or read and write if the agent will open changes
IssuesRead and write if the agent will triage or comment on issues
Pull requestsRead and write if the agent will inspect or comment on pull requests
MetadataRead-only
ActionsRead-only, if the automation should inspect workflow runs
ChecksRead-only, if the automation should inspect check runs
Then click Generate token and copy the token immediately.
If you change token permissions later, you may need to update the token or create a new one.

​
Add the GitHub MCP Server

The GitHub MCP server gives the agent tools for reading repository state and taking GitHub actions.
  1. In Agent Canvas, check the backend switcher in the bottom-left corner.
  2. Make sure the active backend is the backend where you want the repository monitor to run.
  3. Open Customize.
  4. Open MCP Servers.
  5. Select GitHub from the MCP library.
  6. Paste the GitHub token you created earlier.
  7. Save the MCP server configuration.

​
Add the GitHub Token as a Secret

Some automations also need the token available as a backend secret, especially when the agent runs GitHub commands or accesses private repositories.
  1. Open Settings.
  2. Open Secrets.
  3. Click Add a new Secret.
  4. Set the secret name to GITHUB_TOKEN.
  5. Paste the GitHub token as the secret value.
  6. Save the secret.

​
Start the Repository Monitor Workflow

  1. Open Automate in the left navigation.
  2. Find Start from a proven workflow.
  3. Choose the GitHub repository monitor workflow.
  4. Agent Canvas opens a new conversation with a prefilled setup prompt.
  5. Send the prompt as-is, or edit it first if you already know what you want.
After you send the prompt, the agent starts a setup conversation. It uses the preconfigured skills and GitHub access to interview you, clarify the monitoring workflow, and create the automation.

​
Customize the Monitor

You do not need to know every detail before sending the prefilled prompt. The agent will ask follow-up questions to clarify:
  • The repository owner and name
  • The events or conditions the monitor should watch
  • How often the automation should check the repository, if it is schedule-based
  • What the agent should do when it finds a match
  • Where the agent should report results, such as a GitHub comment or Slack channel
You can edit the prefilled prompt before sending it if you want to provide any of those details up front. For example, you can ask the monitor to watch for failed workflow runs, summarize the failure, and open a pull request when the fix is straightforward.

​
Verify the Automation

After the automation is created:
  1. Open Automate.
  2. Confirm the new automation appears in the list.
  3. Open the automation details and check that it is enabled.
  4. Trigger or wait for matching repository activity.
  5. Confirm that the agent run appears and performs the action you requested.