Connect GitHub
Connect GitHub when you want your code outside your workspace, where your team can reach it.
Connecting takes two steps, and sometimes a third. You connect your own GitHub account once, then link a repository to each application you want to store there. If your GitHub organization restricts third-party applications, which are outside apps such as C3 Code that ask to reach the organization's data, an owner of the organization also approves C3 Code one time.
Your account connection is personal, so every colleague connects an account of their own. The repository belongs to the application, so every workspace in that application uses the same repository.
What connecting GitHub gives you
A connected repository provides five capabilities:
- A copy of your code outside C3 Code.
- Two people building on the same application at once, each on a branch of their own, merging when the work is done.
- Review by people outside your workspace, who can also add changes of their own.
- Deployment on a schedule, which builds from GitHub.
- Access to your code in an editor of your own.
A second workspace needs a repository. Create Workspace stays disabled until the application has one connected.
Every workspace already keeps a history of changes, so you can save your work and compare versions before connecting GitHub. Connect at any point, and C3 Code copies the application you have built so far into the repository.
Connect your account
Open your settings and choose one of two ways to connect:
- Open Settings from your profile menu.
- Find GitHub under Git Providers. The status reads Not connected.
- Select either Connect via OAuth or Connect via Fine-Grained Token.
Connect via OAuth sends you to GitHub, where you approve C3 Code once. GitHub returns you to the settings page with the connection made. Choose this route when your organization allows it. Connecting this way also lets the agent read your repositories, issues, and pull requests while the agent builds.
Connect via Fine-Grained Token takes a token you create in GitHub. A token is a password for programs, and a fine-grained token grants only the permissions you select. Choose this route when your organization asks for token access, or when the approval screen is unavailable to you.
Create the token in GitHub with these four permissions:
- Contents: read and write
- Commit statuses: read and write
- Pull requests: read and write
- Metadata: read-only
Paste the token into C3 Code and save. Either route changes the status to Connected, and a Disconnect action appears.
The connection belongs to your account. Every colleague connects an account of their own, and a repository your colleague linked remains inaccessible until you connect your own.
Link a repository to your application
With your account connected, an application Admin links a repository to the application. The admin starts from the Git status control in any workspace, or from the Repository section of the application Settings tab.
Create the repository through C3 Code, which copies your current workspace code into the repository.
For saving, branching, and reviewing your code, see Review Code and Manage Branches.
Give C3 Code access to your organization's private repositories
C3 Code lists the private repositories of a GitHub organization after an owner of that organization approves C3 Code. An organization that restricts third-party applications shows only its public repositories in Select a repository until then.
The approval happens one time for each organization. After an owner grants access, every member of the organization who connects through Connect via OAuth sees the private repositories their GitHub permissions allow.
Request access
Request access during your first connection:
On the Authorize Application pop-up page, find your organization under Organization access. A green check means an owner already approved C3 Code, and an organization with a Request button still needs approval. Select Request.
In the Send request for approval? dialog, select Request approval from owners. GitHub emails the organization owners.
GitHub shows Request only during your first connection. After that, request access from your GitHub settings:
Go to Settings > Applications > Authorized OAuth Apps and open the C3 Code app. GitHub lists it by the URL of your C3 Code environment.
Under Organization access, a green check means an owner already approved C3 Code. Select Request next to an organization that still needs approval.
Tell an owner of the organization that the request is waiting.
Approve the request
An owner of the organization approves the request in the organization settings on GitHub:
- Open your profile menu and select Your organizations.
- Select the organization,
c3code-organizationin this example. - Select Settings > Third-party Access > OAuth app policy.
- Select Review next to the C3 Code application. GitHub lists it by the URL of your C3 Code environment.
- Review the requested access, then select Grant access.
The list in OAuth app policy shows the C3 Code application only after a member sends a request. When the application is missing from the list, ask the member to send the request again.
Connect your account again
After the owner grants access, connect your account again so C3 Code receives the new access:
- In C3 Code, open Settings from your profile menu.
- Select Disconnect under GitHub.
- Select Connect via OAuth and approve C3 Code in GitHub.
The private repositories of the organization now appear when you select a repository to link.
If you connect to GitHub through Connect via Fine-Grained Token, set the Resource owner of the token to the organization. If the organization enables Require approval of fine-grained personal access tokens, its private repositories stay hidden from the repository list until an owner approves your token. To change this setting, an owner of the organization opens the organization's Settings > Third-party Access > Personal access tokens > Settings and chooses an option under Require approval of fine-grained personal access tokens.
Fix a connection problem
The Git status control shows only a link to Settings: your account has no GitHub connection yet. Select Go to Settings and connect an account.
The Git status control is unavailable: its tooltip reads "Application admin access is required to connect a Git repository." Only an application Admin connects a repository. Ask an application admin to connect it, or to give you the Admin role.
A push fails and the application already has a repository: a colleague linked that repository with their own account, and your account is still unconnected. Connect your account in Settings, then push again.
The repository list shows only the public repositories of your organization: your organization restricts third-party applications, and no owner has approved C3 Code yet. Request access and ask an owner to approve it, as described in Give C3 Code access to your organization's private repositories.
A push fails after connecting with a token: the token is missing a permission, or the token has expired. Create the token again in GitHub with all four permissions, then save the token again in Settings.
Where to go next
These pages cover working with the repository you linked: