Worlds / Eng and it ops

GitHub API

A local GitHub with repositories, branches, pull requests, reviews, check runs, issues and branch protection rules. Test the engineering agent that triages issues, reviews and merges pull requests.

Base path: /
Auth: Personal access token or app installation token, the world key
Endpoints: 18
Status: Active today

This reference previews the surface the GitHub world serves in the closed beta. Paths mirror the public GitHub API; the exact subset is confirmed when your workflow is scoped.

Connect

The run gives your agent these bindings. Keep your SDK; change only where it sends requests.

binding	meaning
`WORLDS_GITHUB_URL`	This world's origin followed by `/`
`WORLDS_API_KEY`	The world key, accepted wherever GitHub expects a credential
`WORLDS_WORLD_ID`	The isolated world's identity

js · @octokit/rest

import { Octokit } from "@octokit/rest";

const octokit = new Octokit({
  baseUrl: process.env.WORLDS_GITHUB_URL,
  auth: process.env.WORLDS_API_KEY,
});

const { data } = await octokit.rest.issues.listForRepo({
  owner: "acme",
  repo: "api",
  state: "open",
});

API reference

18 of 18

Repositories

Repos with visibility, default branch and topics.

GET/orgs/{org}/reposList organization repositories
GET/repos/{owner}/{repo}Get a repository
POST/orgs/{org}/reposCreate an organization repository
GET/repos/{owner}/{repo}/contents/{path}Get file contents

Fields · 5

`id`	integer	Repository id
`full_name`	string	owner/name
`private`	boolean	Whether the repo is private
`default_branch`	string	Default branch
`open_issues_count`	integer	Open issues and pull requests

Issues

Issues and their labels, assignees and comments.

GET/repos/{owner}/{repo}/issuesList repository issues
POST/repos/{owner}/{repo}/issuesCreate an issue
GET/repos/{owner}/{repo}/issues/{number}Get an issue
PATCH/repos/{owner}/{repo}/issues/{number}Update an issue
POST/repos/{owner}/{repo}/issues/{number}/commentsComment on an issue

Fields · 6

`number`	integer	Issue number
`title`	string	Title
`state`	string	open or closed
`labels`	array	Labels
`assignees`	array	Assigned users
`user`	object	Author

Pull requests

Pull requests, reviews and merge state.

GET/repos/{owner}/{repo}/pullsList pull requests
POST/repos/{owner}/{repo}/pullsCreate a pull request
GET/repos/{owner}/{repo}/pulls/{number}Get a pull request
POST/repos/{owner}/{repo}/pulls/{number}/reviewsCreate a review
PUT/repos/{owner}/{repo}/pulls/{number}/mergeMerge a pull request

Fields · 6

`number`	integer	Pull request number
`title`	string	Title
`state`	string	open or closed
`head`	object	Source branch
`base`	object	Target branch
`merged`	boolean	Whether it was merged

Organization members

People and teams in an organization.

GET/orgs/{org}/membersList organization members
PUT/orgs/{org}/memberships/{username}Set organization membership
GET/orgs/{org}/teamsList teams
PUT/orgs/{org}/teams/{slug}/memberships/{username}Add a team member

Fields · 4

`login`	string	Username
`id`	integer	User id
`role`	string	admin or member
`slug`	string	Team slug

Test workflow

Prepare. Select the GitHub setup for your workflow and review its starting records, including repositories, issues, pull requests.
Connect. Configure your agent with this world's URL and key using the SDK example. Check that it reaches the intended API before running a test.
Define. Describe the task, expected final changes and records that must stay untouched. Keep expected outcomes separate from the agent's instructions.
Run and inspect. Use the dashboard or your workflow's generated CLI setup. Review final records and changes, then rerun from the same starting setup with the relevant failure conditions. Use Deployment and CI to automate the same workflow.

What to verify

#482 merged into main
#487 still open
#475 closed with a comment
#491 still a draft
No direct pushes to main

Test file

A task file names the jobs, the policy your agent is given and what the grader reads back from the world's final state. The agent never sees the expected outcomes.

yaml · worlds/tasks.yaml

# worlds/tasks.yaml · GitHub
version: 2
connector: github
seed: github-starter
mode: isolated
policy: >
  Merge open PRs on acme/api that have all required checks green and two
  approvals. Close PRs with no activity in 90 days with a comment. Leave
  drafts alone.
tasks:
  - id: merge-pull-requests-that-pass-required-checks-and-reviews
    prompt: Merge pull requests that pass required checks and reviews
  - id: label-and-assign-new-issues
    prompt: Label and assign new issues
  - id: request-reviewers-from-codeowners
    prompt: Request reviewers from CODEOWNERS
expected:
  - "#482 merged into main"
  - "#487 still open"
  - "#475 closed with a comment"
  - "#491 still a draft"
  - No direct pushes to main
scenarios:
  - secondary-rate-limit
  - not-mergeable
  - head-moved

See Tasks and outcomes for every field, and Deployment and CI to run the file on every pull request.

Failure conditions

Each one fires before the handler, at the same step on every run.

condition	what the agent sees
`secondary-rate-limit`	Bursts of writes return 403 with Retry-After
`not-mergeable`	PUT /merge returns 405 while checks are pending
`head-moved`	Merging with a stale sha returns 409
`token-expired`	The installation token expires after an hour
`webhook-redelivered`	pull_request.closed is delivered two times

Starting data

Start each run from the same records and relationships. The overview below describes the GitHub starter; use the setup supplied for your workflow when preparing your own snapshot.

Records	Starting setup
repositories	4 repos with main and release branches
pull requests	30 open, draft, merged and closed
checks	Check runs passing, failing and pending
branch protection	Required reviews and required status checks on main
issues	60 with labels, milestones and assignees

The record shapes below reuse this world's API field definitions. They show illustrative values and placeholders, not an importable seed. API responses and seed input can differ; include all required records and references in the accepted import format for your workflow.

Repositories records

Repositories

Repos with visibility, default branch and topics.

Field	Type	Meaning / relationship
`id`	integer	Repository id
`full_name`	string	owner/name
`private`	boolean	Whether the repo is private
`default_branch`	string	Default branch
`open_issues_count`	integer	Open issues and pull requests

json · illustrative record shape

{
  "id": 1,
  "full_name": "<owner/name>",
  "private": false,
  "default_branch": "<Default branch>",
  "open_issues_count": 1
}

See repositories operations

Issues records

Issues

Issues and their labels, assignees and comments.

Field	Type	Meaning / relationship
`number`	integer	Issue number
`title`	string	Title
`state`	string	open or closed
`labels`	array	Labels
`assignees`	array	Assigned users
`user`	object	Author

json · illustrative record shape

{
  "number": 1,
  "title": "<Title>",
  "state": "<open or closed>",
  "labels": [],
  "assignees": [],
  "user": {}
}

See issues operations

Pull requests records

Pull requests

Pull requests, reviews and merge state.

Field	Type	Meaning / relationship
`number`	integer	Pull request number
`title`	string	Title
`state`	string	open or closed
`head`	object	Source branch
`base`	object	Target branch
`merged`	boolean	Whether it was merged

json · illustrative record shape

{
  "number": 1,
  "title": "<Title>",
  "state": "<open or closed>",
  "head": {},
  "base": {},
  "merged": false
}

See pull requests operations

Organization members records

Organization members

People and teams in an organization.

Field	Type	Meaning / relationship
`login`	string	Username
`id`	integer	User id
`role`	string	admin or member
`slug`	string	Team slug

json · illustrative record shape

{
  "login": "<Username>",
  "id": 1,
  "role": "<admin or member>",
  "slug": "<Team slug>"
}

See organization members operations

See the GitHub world in the catalog