GitHub App

The Crafting system can use a GitHub App to interact with GitHub for capabilities that go beyond what the standard git SSH protocol provides. For self-hosted Crafting deployments, contact the Crafting team to set up the GitHub App.

Connecting the GitHub App

To connect a GitHub App, visit Connect / GitHub in the Web Console as an org admin and follow the steps.

Identity and Permission

Once the GitHub App is connected, repositories in workspace checkouts can be specified using the github format:

workspaces:
- name: example
  checkouts:
  - path: src
    repo:
      github:
        org: GITHUB_ORG
        repo: GITHUB_REPO

Where GITHUB_ORG is the name of the GitHub organization and GITHUB_REPO is the repository name.

When a workspace uses this format, Crafting:

Automatically generates the origin git remote as https://github.com/GITHUB_ORG/GITHUB_REPO.
Injects URL mapping rules to convert other git remote schemas (such as git@github.com:GITHUB_ORG or legacy git://...) to the https://github.com/... format.

This ensures all repositories — including submodules with various remote URL formats — can be checked out by the GitHub App without individual user SSH key registration.

Commits

When pushing commits via the GitHub App:

The author is set to the sandbox owner.
The committer is set to the GitHub App identity.

Access Control Considerations

Because the GitHub App is shared across the entire org, there is no per-user access control on repository access. The org must decide the appropriate access policy based on its security requirements and configure the GitHub App's repository access accordingly.

Using SSH with GitHub App Enabled

When the GitHub App is enabled, Crafting automatically maps git@github.com:GITHUB_ORG remotes to https://github.com/GITHUB_ORG to ensure smooth checkout. If you need to use SSH protocol explicitly (e.g. to push using your personal SSH key), add a git remote with the ssh: prefix:

git remote add upstream ssh:git@github.com:GITHUB_ORG/GITHUB_REPO

Make sure the public key of the Managed SSH Keypair is registered in your GitHub account, then push using:

git push upstream BRANCH