GitHub

Connect GitHub to automate developer workflows: open and triage issues, raise and merge pull requests, comment, manage labels and assignees, read CI status and reviews, run an Actions workflow, and react to repository events. metamorphOS works with the repositories you grant access to, and GitHub notifies metamorphOS by webhook when issues and pull requests change or a deployment succeeds.

What you can do

• Issues: create, view, update, close, and list issues, and add comments.
• Pull requests: open, view, list, and merge pull requests, and read a pull request’s reviews and approvals.
• Labels and assignees: add and remove labels on an issue, and assign people to issues and pull requests.
• Repositories and CI: read repository details, check the combined CI status of a commit, and start a GitHub Actions workflow.
• Repository events: trigger a process automatically when an issue is opened, an issue is labeled, an issue is closed, a pull request is merged, or a deployment succeeds.

Before you start

You need a GitHub account with access to the repositories you want to automate, and permission to register an OAuth app on your account or organization. To receive events, you also need admin access to each repository so you can add a webhook.

Set up GitHub

1. Register an OAuth app. In GitHub go to Settings -> Developer settings -> OAuth Apps -> New OAuth App. Give it a name (for example, metamorphOS) and a homepage URL.
2. Set the callback URL. In Authorization callback URL, enter the redirect URL metamorphOS shows for this connector. GitHub sends the browser back here after you approve access.
3. Copy the credentials. After creating the app, note its Client ID and generate a Client secret. GitHub shows the secret only once, so copy it right away.

Connect in metamorphOS

Activate the GitHub connector from the marketplace and add an account. Enter the app’s Client ID and Client secret, then start the connect flow: metamorphOS sends you to GitHub to sign in and approve access to your repositories and to manage repository webhooks. After you approve, GitHub returns you to metamorphOS and the account is connected.

Receive events (webhooks)

To trigger a process when issues, pull requests, or deployments change, add a webhook on each repository you want to watch. In the repository go to Settings -> Webhooks -> Add webhook and set:

• Payload URL: the receiver URL metamorphOS provides for this connector. One URL handles all of the events below.
• Content type: application/json.
• Secret: a signing secret you choose. Enter this same value on the connector’s account in metamorphOS as the webhook signing secret.
• Which events: choose Let me select individual events and tick Issues, Pull requests, and Deployment statuses.

GitHub signs each delivery with your secret so metamorphOS can confirm it is genuine, and rejects any delivery that fails verification.

Set up for an agentic software lifecycle

A common use of this connector is to run development work through GitHub: issues carry the state of each piece of work, a process reacts when that state changes, an agent implements, and a pull request comes back for a human to accept. Five things need to be true before that works, and two of them are easy to miss.

1. Let a dedicated account do the consenting

This is how you choose which repositories metamorphOS can reach. The connector authorises with OAuth, so the token acts as the person who approved it, limited to what that person can already see. There is no repository field on the connector itself.

Create a machine account, give it write access to the target repository and nothing else, and run the connect flow while signed in as that account.

If you consent as yourself instead, metamorphOS acts as you. It can reach every repository you can, and every issue, comment and pull request it creates is attributed to you, so nobody can tell later which work was automated and which was yours.

2. Keep that account unable to merge

The account needs write access to push branches and open pull requests. It should not be able to land them. Restrict who may push to your default branch to your human reviewers, and leave the machine account off that list. Merging is a push to the branch, so the restriction covers it, and you get a record on every merge showing that the author and the accepter were different people.

3. Create your labels before the first run

The connector can add and remove labels, but it cannot create one that does not exist yet. Add the labels your process expects up front, or the first attempt to advance a piece of work fails on a label GitHub has never heard of.

gh label create "phase: captured" --description "Reported, not yet triaged"
gh label create "phase: triaged"  --description "Real, classified, worth doing"
gh label create "phase: shaped"   --description "Ready to hand to an implementer"

Use whatever names your process uses. The point is that they exist first.

4. Tell the package which repository to use

Every outbound function takes owner and repo as parameters, which keeps the connector usable across repositories. Set them once in your package, in a datastore entry or a package parameter that every step reads, rather than typing them into each instruction. Repeating them per call is the most common reason a package works against one repository and silently misses in another.

5. Subscribe to the events that drive the flow

For this use case the two that matter are Issues and Pull requests. Add Deployment statuses only if you also want to record what reached production.

A labeling event is what usually moves work forward, because the label is where the state lives. It arrives as its own trigger, so a process can wait on a specific label rather than polling.

What stays with a human

The connector can open a pull request, and it can merge one. Whether it is allowed to merge is decided by your branch protection, not by the connector. Restricting the push and leaving merging to a person is what keeps the final acceptance a human decision.

Good to know

• A merged pull request and a closed issue both arrive as the underlying “closed” event; the connector only starts a process for the specific outcome each trigger describes.
• Field coverage is trimmed to what the connector uses, so extra details present in a live GitHub response are simply ignored.