Getting started

How Buddy works

DevOps Buddy is a hosted app. There's nothing to install and no change to your pipelines. With two read-only tokens it:

• reads your GitHub Actions runs and your Cloudflare Workers, Pages, D1, R2, KV, zones and DNS;
• groups them into services, the way your team talks about them;
• turns failed runs, failed deployments and Worker error spikes into incidents, each with a root cause;
• answers questions about all of it in Ask Buddy.

If you also add a separate write token, Buddy can fix things: open a pull request with a proposed change, follow up on failing checks, and retry or roll back deployments. Every one of those actions shows a preview and waits for someone to approve it. See Fixes and actions.

1. Create your account

1. Open the sign-up page.
2. Enter your name, work email and a password, then choose Create account.
3. Onboarding walks you through the next steps. You can leave and pick up where you stopped.

Just looking? The live demo opens a read-only workspace for a fictional company, no account needed.

2. Create a workspace

A workspace holds one team's connections, services, incidents and audit log. Name it after your team or company (you can rename it later in Settings → Workspace).

Need to keep things apart, for example a client's stack and your own? Create another workspace from the workspace switcher in the top bar. Nothing is shared between workspaces.

3. Connect GitHub

Use a fine-grained personal access token. It can be limited to specific repositories and to read access.

1. On GitHub, open Settings → Developer settings → Personal access tokens → Fine-grained tokens and choose Generate new token.
2. Name it (for example devops-buddy-read) and pick an expiration.
3. Under Resource owner, choose the organization that owns your repos (or your own account).
4. Under Repository access, choose All repositories or Only select repositories.
5. Under Permissions → Repository permissions, set exactly these three and leave everything else at No access:

• ActionsRead-only
• ContentsRead-only
• MetadataRead-onlyAdded automatically.

6. Choose Generate token and copy it. GitHub only shows it once.
7. In Buddy, paste it into the Connect GitHub step (or Settings → Connections → GitHub) and save.

Buddy checks the token with a read call and shows the account and repositories it can see. If your organization requires approval for fine-grained tokens, its repos appear once an owner approves the request.

4. Connect Cloudflare

Use an API token made from Cloudflare's read-only template.

1. In the Cloudflare dashboard, open My Profile → API Tokens and choose Create Token.
2. Next to the Read all resources template, choose Use template. It grants read access to everything and write access to nothing.
3. Optionally narrow Account Resources and Zone Resources to what you want Buddy to see.
4. Choose Continue to summary → Create Token and copy the token.
5. In Buddy, paste it into the Connect Cloudflare step (or Settings → Connections → Cloudflare) and save.

Buddy checks the token with a read call and shows the accounts it can see.

Advanced: Global API Key

If you can't create scoped tokens, Buddy also accepts your Global API Key together with your Cloudflare account email for the read connection. Find it under My Profile → API Tokens → Global API Key → View, then choose Global API Key as the connection type in Buddy.

5. Review your services

Once a connection is saved, Buddy lists every resource it can see and proposes services: groups of repos, Workers, Pages projects, D1 databases, R2 buckets, KV namespaces and zones that belong together. For example, Checkout might be the shop-api repo, the checkout-edge Worker, the orders database and the receipts bucket.

Suggestions come from resource names, the repo each Pages project builds from, and the bindings each Worker uses. On the review step you can:

• rename a service, or give it a description and colour;
• merge two suggestions, or move a resource from one service to another;
• leave resources ungrouped. They still show up everywhere, just without a service.

A resource belongs to at most one service. You can edit services any time from the service page. The home screen shows what needs attention first: failing and degraded services, then the quiet ones.

Root cause analysis

Three things become incidents: a failed GitHub Actions run, a failed Pages deployment, and a spike in a Worker's errors. Each incident gets a root cause analysis with:

• a one-sentence summary and a fuller root cause;
• a category (test failure, build error, dependency, config, infrastructure, flaky, code bug, permissions, rate limit or unknown) and a confidence, stated in words;
• evidence: the log lines or data points it relied on, with line numbers;
• a suggested fix and next steps.

An analysis is written the first time someone opens the incident (or as soon as a new incident appears), then kept for that incident, so everyone on the team sees the same answer. If the evidence is thin, Buddy says so with a low confidence or an unknown category rather than guessing.

Fixes and actions

Buddy reads by default. To let it open pull requests and run actions such as rollbacks, add a separate write connection for GitHub, Cloudflare or both in Settings → Connections. Your read connections stay exactly as they are and never gain write access. Without a write connection, fix and action buttons explain what's missing and stay disabled.

GitHub write token

Create a second fine-grained token, limited to the repositories you want fixes for. Name it something like devops-buddy-write, then set these repository permissions:

• ContentsRead and writeCreate the buddy/* branch and commit the fix.
• Pull requestsRead and writeOpen the pull request and reply to review comments.
• ActionsRead and writeRe-run failed jobs and start a workflow_dispatch deploy.
• MetadataRead-onlyAdded automatically.

Cloudflare write token

In My Profile → API Tokens, choose Create Custom Token and add these account permissions, limited to the account Buddy should act on:

• Cloudflare PagesEditRetry a failed deployment, or roll back to a previous one.
• Workers ScriptsEditRoll a Worker back to its previous version.

Fix with Buddy

1. On an incident with a root cause, choose Fix with Buddy. Buddy reads the files the evidence points to, the failing commit's changes and the workflow file, and drafts a small patch with its risk and the tests to run.
2. Review the diff in Buddy. Choose Open pull request and confirm in the dialog.
3. Buddy creates a buddy/fix-… branch, commits the change, and opens a pull request labelled devops-buddy with the root cause, evidence and risk in the description.
4. If checks fail, Buddy reads the new failure and pushes a follow-up commit, up to three attempts by default. If a reviewer requests changes or comments @buddy …, or you type a change request in the app, it revises the change and replies.
5. A person merges. Buddy never does.

Every step appears in the fix's timeline in Buddy and on the pull request.

How approvals work

Every write starts with a preview: each effect in plain words, whether it can be undone from Buddy, and which permission it uses. If the permission is missing, the dialog says which one and the confirm button stays disabled. You confirm with a button that names the action, such as Open pull request, Roll back or Deploy to production. Actions that can't be undone, or that change production for everyone, ask you to type the resource name first.

Approving a fix's pull request also covers Buddy's follow-up commits on that same branch. Anything else needs its own approval.

What Buddy will and won't do

Audit log

Settings → Audit log lists every approval and action in the workspace: who approved it, when, the target, the result, and a link to the pull request, run or deployment.

Ask Buddy and briefs

Ask Buddy answers questions in plain English, like "why did checkout-edge start erroring?", by looking things up with the same read-only access the dashboard uses, scoped to your workspace. Each answer lists the lookups it made so you can check its work. You can also start a question from any run, deployment or Worker with Ask about this.

Buddy's brief is a short paragraph for the workspace and for each service: what changed, what's broken, and where to look first. Briefs refresh about every half hour.

Teammates

Invite teammates by email from Settings → Members. Everyone in a workspace sees the same services, incidents, analyses and audit log. Workspaces have three roles: owner, admin and member.

Security and data

Read-only by default

Everything Buddy reads from GitHub, Cloudflare or the AI provider goes through one function, readOnlyFetch(). It allows GET and HEAD, and POST only to these read endpoints:

• Cloudflare GraphQL analytics (/client/v4/graphql)
• Workers Observability log queries (/workers/observability/telemetry/query)
• OpenAI Responses (/v1/responses), for root causes, briefs, fixes and Ask Buddy

Anything else is refused before the request leaves Buddy, and a test holds the rule in place.

Changes only with your approval

Writes use a separate function, actionFetch(), with its own explicit list of allowed endpoints (the ones in What Buddy will and won't do). It only uses write connections, only accepts a request that carries an approval from a person in your workspace, and records every call in the audit log. Branch updates are limited to buddy/* branches.

Tokens are write-only and encrypted

You paste a token once. It's encrypted with AES-256-GCM, with a fresh IV for every record, before it's stored. It's decrypted only inside the request that needs it, and it's never logged, never shown again and never sent back to a browser. Buddy keeps a few details about each connection so you can recognise it: the GitHub login, Cloudflare account names and token scopes.

Isolated per workspace

Connections, services, root causes, fixes and audit events belong to one workspace. Every query is scoped to the workspace in your session, and people only see workspaces they've joined.

What we store

• Your account: name, email and a hashed password.
• Your workspaces, members and invitations.
• Connections: the encrypted token and the details above.
• Services and which resources belong to them.
• Root cause analyses (including the log lines they quote as evidence) and briefs.
• Proposed fixes, their diffs and timelines.
• The audit log of approvals and actions.

Runs, logs, deployments and analytics are read live from GitHub and Cloudflare when you open a page. They aren't copied into our database.

What the AI provider sees

Buddy uses the OpenAI API. For a root cause it sends the relevant log excerpts and details of the failing run, deployment or Worker. For a fix it also sends the contents of the files involved. For Ask Buddy it sends your question and the results it looked up to answer it. For service suggestions it sends resource names and how they link together. Your tokens are never sent.

Revoke and delete

Remove a connection

In Settings → Connections, remove any read or write connection. Its encrypted token is deleted and Buddy stops using it straight away. You can also revoke the token at the source: on GitHub under Settings → Developer settings → Personal access tokens, or in Cloudflare under My Profile → API Tokens. Removing only the write connection puts Buddy back to read-only.

Delete a workspace

A workspace owner can delete it from Settings → Workspace. This permanently removes its connections and their tokens, services, root causes, briefs, fixes, audit log and member list. It can't be undone. Pull requests Buddy opened stay in GitHub; close them there if you no longer want them. For a clean finish, revoke the tokens at GitHub and Cloudflare too.

Troubleshooting

Buddy rejects my token when I save it

Buddy checks every token before saving it. A rejection usually means it expired, was copied incompletely, or is missing a permission. Create a new one with the permissions above.

My organization's repos don't show up

Check the token's Resource owner is the organization, not your personal account, and that it covers those repos. Some organizations require an owner to approve fine-grained tokens; until they do, the repos stay hidden.

Fix with Buddy or Roll back says "Needs write access"

The workspace has no write connection for that provider, or the token lacks the permission the dialog names. Add or update the write connection in Settings → Connections with the scopes in Fixes and actions.

The pull request couldn't be opened

GitHub refused the push or the pull request. Common reasons: the write token doesn't cover that repository, the fix touches .github/workflows without the Workflows permission, or an organization rule blocks new branches. The error in Buddy names what GitHub returned.

Worker logs are empty

Turn on Workers Observability for that Worker and redeploy it. Logs only cover events after it's enabled.

A root cause says "unknown" or has low confidence

The failure left little to go on: the logs may have expired or the job stopped before printing an error. Open the evidence and the full log from the incident; you can also ask Buddy a follow-up question.

I can't change anything in the demo

That's by design. The demo workspace is read-only for everyone. Create an account to connect your own stack.