GitHub Connection

A GitHub connection links your OSC workspace to a GitHub account or organization through the OSC GitHub App. Once connected, your My Apps, My Jobs and My Agent Tasks can read private repositories (and, for agent tasks, push branches and open pull requests) without you creating or pasting a personal access token. OSC hands each app, job or task a short-lived token (valid for one hour) that only covers the repositories that item needs. How the token is renewed depends on the feature and is described under Using a Connection.

When to Use It

Use a connection when you want repository access that you never have to copy, rotate or renew. Use a fine-grained personal access token (PAT), a Git Credential or a GH_TOKEN in a parameter store when you need something the connection does not cover: repositories under more than one GitHub account in a single task, pushes that change files under .github/workflows/, forking a repository you do not own, or pushing images to ghcr.io.

You want Use
Private repo access with nothing to rotate GitHub connection
One task that touches repos in two GitHub accounts PAT or Git Credential
An agent that pushes workflow files or forks third-party repos PAT as GH_TOKEN in the parameter store
An existing setup that already works Keep it, nothing changes

An explicit credential wins over a connection. If a My App or agent task has a Git Credential or token set, that is what it uses, and a request that sets both a credential and a connection is rejected. For the gh command inside an agent task, a GH_TOKEN in the bound parameter store always takes precedence over the connection. Nothing is changed on existing apps, jobs or tasks when you create a connection; they only use it when you select it.

Connect GitHub

  1. Open My Apps in the web console and select the Git Credentials tab. The GitHub connections section is at the top.
  2. Select Connect GitHub, then Continue to GitHub.
  3. On GitHub, choose the account or organization that owns your repositories and install the OSC GitHub App. Install it broadly (all repositories, or a wide selection). OSC narrows each token to the repositories a given app, job or task needs, so a broad install does not give every item access to everything.
  4. GitHub sends you back to OSC and shows the Confirm connection screen. Check the account shown there. Then pick a connection name (1 to 40 lowercase letters, numbers or dashes; it defaults to the account name) and select Save connection. You have 10 minutes from the moment GitHub sign-in succeeds to do this.

The connection then appears in the list with a Connected label. Use the list icon to see which repositories it can reach (select Refresh to reload them) and the Installation settings on GitHub link to change them.

Anyone in your OSC workspace can use any repository the App can see, in the same way as a shared Git Credential, so install it only on accounts you are happy to share with the whole workspace.

Who Can Connect and Owner Approval

Only the owner of the GitHub account can connect it. For a personal account that is the account holder. For an organization it is an organization owner. OSC checks this against GitHub, and if the GitHub user who signed in is not an owner it refuses with "Your GitHub user cannot use this installation. Sign in to GitHub as a user with access, or ask an owner of the account to connect it." (HTTP 403 not_installation_owner).

If you are a member but not an owner, GitHub does not install the App. It sends an install request to the organization owners, and OSC shows Waiting for approval. The sequence is then:

  1. An owner of the organization approves the install request on GitHub.
  2. An owner returns to OSC, signed in to the OSC workspace that should get the connection, and opens the Git Credentials tab in My Apps. A member cannot finish it, because OSC runs the same owner check again and refuses a non-owner.
  3. The owner enters the exact GitHub login of the organization and selects Finish connecting, signs in to GitHub, and lands on the Confirm connection screen.
  4. The owner picks a name and selects Save connection.

The requester cannot complete steps 2 to 4 on their own. The owner must do them from an OSC account that belongs to the workspace, or the requester can ask the owner to connect it directly.

Adding Repositories Later

OSC cannot add repositories to the GitHub installation. If you installed the App on selected repositories only, add more on GitHub through the Installation settings on GitHub link, then return to OSC and select Refresh in the repository list or picker. A repository that is not in the installation is rejected with "This repository is not in the GitHub installation. Add it in your GitHub installation settings, then select Refresh."

Using a Connection

My Apps

In the Create App dialog, select Use GitHub connection under the git token options and pick the connection. The repository must belong to the account the connection is installed on. OSC refreshes the app's token in the background. If a refresh fails you see nothing, and the app only fails when its next restart cannot clone the repository.

My Jobs

The job form has one git credential dropdown with two sections, Saved credentials and GitHub connections. Pick one or the other; a job cannot have both, and the API rejects a request that sets both a Git Credential and a connection. A fresh token is created every time the job runs.

My Agent Tasks

In the task form, under GitHub access, choose GitHub connection (the other choices are Stored git credential, Paste a token and none). Pick the connection, choose Read only or Read and write, and select the repositories. A repository that is not in the installation is flagged so you can add it on GitHub and refresh. A task can use up to 50 repositories, all under the one GitHub account of its connection.

Git inside the run uses a token that the runner (the program that executes your task) refreshes every 45 minutes while the run is active, so long runs keep working. The gh command inside the run gets the connection token through a wrapper (a small script placed in front of gh), unless you have set GH_TOKEN in the task's parameter store, in which case that value is used. With read and write access, tasks can push and use pull requests and issues. Read access to checks, commit statuses and workflow runs is included, so gh pr checks works.

The runner image (the packaged runner software) must be recent enough to include the token refresh. An older runner image keeps working for one hour and then fails git operations with an authentication error.

Using the Connection from AI Assistants (MCP)

AI assistants reach OSC through MCP (Model Context Protocol), which exposes OSC actions as tools. Connections are referenced by name only. No tool accepts or returns a token.

Tool Use
list-github-connections List your connections with name, account, repository selection and status
create-my-app, update-my-app-github-token Pass githubConnection instead of gitCredential
create-my-job, update-my-job Pass githubConnection instead of gitCredential
create-agent-task, update-agent-task Pass githubConnection, githubRepositories (owner/name, 1 to 50) and githubAccess (read or write) together

Combining githubConnection with gitCredential or gitToken is rejected, and the choice in a request replaces whatever was stored before.

List my GitHub connections, then create an agent task that works on myorg/myrepo with read and write access.

Removing a Connection

Select Remove connection on the connection row. If apps, jobs or tasks use it, OSC lists them and offers Remove anyway. Those items then lose access to private repositories until you give them another credential; they never fall back to anonymous or another identity silently. Removing the connection does not uninstall the App on GitHub. Use the installation settings link on GitHub for that.

Limits and Troubleshooting

What you see Meaning and what to do
The Connect GitHub button is hidden, with "Connecting a GitHub account is not available in this environment." or "GitHub connections are not available in this environment." The feature is not configured where you are signed in. The first build was planned for OSC hosts only (ADR-0069 Q4).
"Your GitHub user cannot use this installation..." You are not the account holder or an organization owner. Ask an owner to connect it.
"The GitHub sign-in expired or was already used." / "This connection request has expired." Select Connect GitHub and start again. The confirmation lasts 10 minutes after GitHub sign-in succeeds.
"You already have a connection with this name. Choose another name." Connection names are unique in a workspace.
"Every repository must belong to the GitHub account of the connection." One token covers one GitHub account. Use a PAT for repositories under another account.
"GitHub has suspended the installation for this account. Access returns when it is unsuspended." Status shows Suspended on GitHub. Unsuspend it on GitHub.
"The OSC GitHub App was uninstalled from this account on GitHub. Connect again, or choose another access method." Status shows Removed on GitHub. Reconnect.
"GitHub did not respond. Try again in a moment." Temporary. Retry.

An app, job or task that has a connection selected never retries with a different credential if the connection fails. It fails with a message naming the problem instead. Manual job runs and agent-task runs show that reason, and a failed agent-task run also appears in the run history with it. A scheduled job run that fails because GitHub is temporarily unavailable (HTTP 503) is silent, so check the job's last run status if a scheduled job stops working.

The OSC GitHub App does not request the GitHub Workflows permission, so pushes that change .github/workflows/ are refused. Use a PAT for those. Forking third-party repositories also needs a PAT, and pushing images to ghcr.io needs a classic personal access token. Apps and jobs only accept repository URLs on github.com.

Glossary

GitHub App: an integration that you install on a GitHub account or organization and that GitHub lets act within the repositories you choose.

Installation: the GitHub App installed on one account or organization.

MCP: Model Context Protocol, the way AI assistants call OSC tools.

Runner image: the packaged software that executes an agent task.

Wrapper: a small script that sits in front of a command and sets it up before it runs.

Personal access token (PAT): a password-like token you create on GitHub and paste into OSC.

Parameter store: a private, encrypted place for an app's settings, where GH_TOKEN can be set.