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 card 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, find the GitHub card. Click Connect GitHub.
3. The card switches to a Connecting state and 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 on the card.
4. On the GitHub page, enter the one-time code and approve access.
5. When GitHub confirms, the card 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 card status pill tells you where you are: Disconnected, Connecting, Connected, or Error.

Disconnecting GitHub

On the Connected card, 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 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, 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. Castforge gives you two ways to set it.

Per project (recommended for a specific repo)

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. 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 (so your real email is not exposed in commits). Click Use my GitHub identity to accept, or Not now to skip.

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 card explains in plain language what the service is for, shows a status pill (Connected, Not connected, or Coming soon), and offers a Connect button. When you click Connect, Castforge opens your browser to complete sign-in for that service, then returns you to a Connected state. Connected cards offer a Manage menu with View account and Disconnect.

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.

Two more are visible but marked Coming soon, so their Connect button is not active yet:

• Cloudflare
• Railway

You may also see a few read-only service cards (for example, Stripe and Neon) that are shown for reference and are not yet wired for a live connection.

The CLI sign-in row on Vercel and Supabase cards

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

Next to a small status dot (lit when signed in), the row 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.

Why are there two statuses? The card'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 card can read Not connected while the CLI can still act through its own login. This row makes that visible. The small help icon on the row opens a short explanation of exactly this distinction.

When the CLI is signed in, a Log out button appears on the 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. The GitHub card there is the one with Connect GitHub.

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. 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) card 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 row at the bottom of the card 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.