GitHub and integrations

Connecting your GitHub account

Castforge connects to GitHub with the GitHub device flow, so you never type a GitHub password (or paste a token) into the app. You approve the connection in your browser, and the resulting token is stored in your operating system keychain on your machine. It never leaves your computer.

The GitHub row lives under Settings, in the Connections section, in the Dev Infrastructure group.

1. Open Settings and go to Connections.
2. In the Dev Infrastructure group, click the GitHub row to expand it, then click Connect GitHub.
3. The row switches to a Connecting state and the expanded area shows a short one-time code (for example, a code like WXYZ-1234). Your browser opens to github.com/login/device automatically. If it does not, click Open github.com/login/device in the expanded row.
4. On the GitHub page, enter the one-time code and approve access.
5. When GitHub confirms, the row flips to Connected and shows the account it connected as. You will see a confirmation that GitHub is connected.

A few things worth knowing:

• The code is short-lived. If it expires before you approve it, click Connect GitHub again to get a fresh code.
• There is a Copy button next to the code so you can paste it on the GitHub page.
• The row status pill tells you where you are: Disconnected, Connecting, Connected, or Error.

Disconnecting GitHub

Expand the Connected GitHub row, click Disconnect, and confirm. This removes the saved GitHub token from this machine. Your account on GitHub stays intact, and you can reconnect any time.

Publishing a project to a new GitHub repository

Once GitHub is connected, you can create a brand new repository for the project you are working on and push your current branch to it in one step. The control is the Git button in the top bar of your project. When the project has no GitHub remote yet, that button reads Git and acts as a Publish button.

1. Click the Git button. The Publish to GitHub dialog opens.
2. Check the repository name. It is prefilled from your project name and cleaned up into a GitHub-safe form (lowercased, spaces and other characters collapsed to hyphens). You can edit it.
3. Optionally add a one-line description.
4. Leave Private repository checked to keep your code private. New repositories are private by default. Only you and people you add can see a private repository. Uncheck the box only if you want a public repository.
5. Click Publish.

Castforge creates the repository on your GitHub account, wires it up as the origin remote, and pushes your current branch.

If a repository with that name already exists on your account, publishing still goes through. This applies to both publish paths: the Publish dialog described here and the automatic publish that runs when you create a new project. When the existing repository is empty, Castforge simply uses it. When it already has commits, Castforge leaves your existing repository untouched and publishes to the next free name instead (name-2, name-3, and so on). The confirmation message always shows exactly which repository was used, so you know where your code landed.

If your working tree has uncommitted changes

Publishing pushes commits only. It does not automatically commit your uncommitted changes. If your project has uncommitted changes when you publish, Castforge stops and asks you to choose, so nothing is silently left behind:

• Commit all and publish: Castforge makes a commit (you can edit the prefilled message) and then publishes. This is the recommended choice and is highlighted.
• Publish committed only: publishes what is already committed and leaves your uncommitted changes on this computer.
• Cancel: backs out so you can review your changes first.

This is the same three-way choice you get when pushing (see below), so the rule is consistent everywhere: pushing and publishing send commits, and your uncommitted changes stay on your machine until they are committed.

Quick commit, push, and pull

Your agents commit on their own as they work. The quick commit dialog is for your own touch-ups: a manual commit, push, or pull.

In the quick commit dialog:

1. The message field is prefilled based on the files that changed (for example, Update 3 files). Edit it if you like.
2. Click Commit to commit your changes locally.
3. Click Push to send your commits to GitHub, or Pull to bring down commits from the remote.

When you click Push with uncommitted changes in your working tree, Castforge shows the same three-way choice described above: Commit all and push, Push committed only, or Cancel. This prevents the common surprise of pushing and then wondering why uncommitted changes are still showing locally. Pushing only ever sends commits.

If a push or pull fails because your GitHub token has expired or been revoked, Castforge tells you plainly and points you to reconnect GitHub in Settings. If a commit fails because no git identity is configured (rare once GitHub is connected, since projects then default to your GitHub account identity), Castforge points you to your Project Settings to set one (see Setting your git commit identity below).

Creating a pull request

When your project has a GitHub remote, you can open a pull request from inside Castforge. The create pull request dialog collects:

• Title (required).
• Head branch (the branch you are proposing to merge) and Base branch (the branch you are merging into). The base branch defaults to main. The head and base must be different.
• An optional description.

Click Create pull request. Castforge creates the pull request on GitHub and then opens it in your browser so you can review it there.

Note: Castforge creates pull requests, it does not yet provide an in-app pull request review surface. After the pull request is created you continue the review on github.com. If GitHub rejects the request (for example, there are no commits between the two branches, or a pull request already exists for them), Castforge shows GitHub's message so you know exactly what to fix.

The sync status indicator

The Git button in the top bar doubles as the live sync indicator for the current branch against its GitHub upstream. It has three states:

• Git (publish): the project has no upstream yet. The button is a call to action to publish to GitHub.
• Publishing: a publish or push is in progress. The button is briefly disabled.
• Synced: the project has an upstream. The button shows how far your local branch has diverged.

When the branch is Synced, the button shows your position relative to the remote:

• If you have local commits the remote does not, it shows how many you are ahead (for example, 2 ahead).
• If the remote has commits you do not, it shows how many you are behind (for example, 1 behind).
• If both are true, it shows both (for example, 2 ahead, 1 behind).
• If neither is true, the button simply reads Synced, which means you are in sync with the remote.

Clicking the button while Synced pushes your branch (with the same dirty-tree choice described above if you have uncommitted changes). The indicator refreshes on its own every few seconds.

Setting your git commit identity

The name and email attached to your commits come from your git identity. With GitHub connected, Castforge handles this for you by default, and you can override it whenever you want.

The default: your connected GitHub account

When GitHub is connected, projects that Castforge sets up with git use your connected GitHub account for commits automatically: your GitHub name and a private GitHub noreply email address (so your real email is not exposed in commits), stored in that repository's own local git config. Every commit made in the project, including the ones your agents make, is attributed to your GitHub account, even on a machine whose global git identity belongs to someone else (a work account, for example).

A few guarantees:

• Your machine's global git identity is never changed.
• If you already set an identity for that project yourself, Castforge leaves it alone.
• Projects created before this change pick up the same identity the next time you publish them, unless they already have one.

Per project (overrides the default)

Open the project's Settings and find the Git identity card. It reads the identity stored in the project's own git config and lets you set:

• Name (for example, Jane Doe).
• Email (for example, jane@example.com).
• Default branch (for example, main).

Click Save. Because this is stored in the repository's local git config, your editor, terminal, and agents all see the same identity for that project. Saving your own values here always wins: Castforge never overwrites an identity you set yourself, so the automatic GitHub-account identity steps aside. After saving, Castforge re-reads the values so you can confirm they took.

Globally, from your GitHub account

Right after you connect GitHub, Castforge can offer to set a global git identity for you in one click, using your GitHub account name and a private GitHub noreply email address. Click Use my GitHub identity to accept, or Not now to skip. This covers repositories outside Castforge and machines with no git identity at all.

This only writes a global identity if you do not already have one. If a global identity already exists, Castforge leaves it untouched and tells you so. You can always override it per project using the Git identity card above.

Other developer integrations

Beyond GitHub, Castforge connects your dev infrastructure so your agents can use those services as tools, scoped per project. You manage these in Settings, in the Connections section, under Dev Infrastructure (the same place as GitHub).

Each service is a compact row showing the service icon and name, a one-line description of what it is for, a status pill (Connected, Not connected, or Coming soon), and a short action hint. Clicking a live row expands it to reveal Connect (or, when connected, the Manage menu with View account and Disconnect). When you click Connect, Castforge opens your browser to complete sign-in for that service, then returns you to a Connected state.

Affiliate partners show a small Partner link note. Castforge may earn credits when you sign up through that partner.

The services that ship today:

• GitHub: described above. Connect once to publish repos, push, and open pull requests.
• Vercel: connect to deploy and manage hosting.
• Supabase: connect to use your Supabase project (database, auth, storage) as a tool.

Three more are visible but marked Coming soon, so their row is inactive for now:

• Cloudflare
• Stripe
• Neon

The CLI sign-in status on Vercel and Supabase rows

The Vercel and Supabase rows show a second, separate status: whether that provider's command-line tool (its CLI) is signed in on this machine with its own login.

The status appears in the row's muted second line (for example, "Partner link · CLI signed in as yourname"). It reads Checking CLI sign-in... while it checks, then one of CLI not signed in, CLI signed in, or CLI signed in as <username> when it knows which account the CLI is using. The full CLI row, with a small status dot, a help icon, and the Log out button, lives in the expanded row.

Why are there two statuses? The row's Connected pill is about your Castforge connection, the one Castforge uses when it runs the CLI for your agents. The CLI also keeps its own sign-in on disk and falls back to it when no Castforge connection is set. That means a row can read Not connected while the CLI can still act through its own login. This status makes that visible. The small help icon in the expanded row opens a short explanation of exactly this distinction.

When the CLI is signed in, a Log out button appears next to the CLI status in the expanded row. Clicking it signs the CLI itself out on this machine (it clears the CLI's own saved login) and never touches your Castforge connection. You will see a "Logged out of the Vercel CLI." (or Supabase) notice when it completes.

Use Log out when you want agents to act only through your Castforge connection, or when the CLI is signed in to the wrong account.

Common questions

I do not see a Connect GitHub button. Where is it?

It is under Settings, in the Connections section, inside the Dev Infrastructure group. Click the GitHub row to expand it; Connect GitHub is inside.

My one-time code stopped working.

Device codes expire after a short window. Just click Connect GitHub again to get a fresh code, then enter the new code at github.com/login/device.

Push failed and it mentioned reconnecting GitHub.

Your saved GitHub token may have expired or been revoked. Open Settings, go to Connections, and reconnect GitHub, then try the push again.

The repository name is taken.

GitHub returns an error when a repository of that name already exists on your account. The Publish dialog stays open and shows GitHub's message. Pick a different name and click Publish again.

I published but my local still shows uncommitted changes.

Publishing and pushing send commits only. Your uncommitted changes stay on your computer until you commit them. Use Commit all and publish (or Commit all and push) to include them, or commit first with the quick commit dialog.

My commit was rejected and it mentioned Project Settings.

That means no git identity is configured, which is rare once GitHub is connected because projects then default to your GitHub account identity. Open the project's Settings, fill in the Git identity card (name and email), and save. Then commit again.

Can I make the repository public?

Yes. New repositories are private by default. Uncheck Private repository in the Publish dialog before you click Publish.

Can I review a pull request inside Castforge?

Not yet. Castforge creates the pull request and opens it in your browser. You review and merge it on github.com.

Where is my GitHub token stored? Is it safe?

It is stored in your operating system keychain on your machine, and it never leaves your computer. Castforge uses the device flow, so you never enter a GitHub password or paste a token into the app.

The Vercel (or Supabase) row says Not connected, but my agents can still deploy. Why?

The provider's CLI has its own sign-in on this machine, separate from your Castforge connection, and it falls back to that login when no connection is set. Check the CLI sign-in status on the row's second line (or expand the row for the full CLI sign-in details) to see whether the CLI is signed in and as which account. Click Log out there if you want to clear it.

What does "Synced" with no number mean?

It means your local branch matches the remote: nothing to push and nothing to pull. When there is a difference, the button shows it as a count, such as 2 ahead or 1 behind.