Import and sync Git repositories

GitHub import with sync metadata

Import a GitHub repository into an organization Home path and attach the information Composal needs to keep it synchronized. For the guided interactive path, start with com repo import --org <org-slug>.

com import github <owner>/<repo> \
  --org <org> --path apps/<slug> --virtual-repo <slug> \
  --github-app-installation-id <id> \
  --sync-branch main --sync-mode bidirectional --yes

Use --skip-sync when you want a one-time import without a continuing external-sync contract.

Protect coordinated Home changes in GitHub

A Home Change can open pull requests in more than one GitHub repository. Composal posts a Composal / coordinated landing Check Run on every component pull request so reviewers can see that the pull requests must land together in Composal.

GitHub only blocks its Merge button when a repository rule requires that check. A repository owner controls that protection. Composal reads the effective rules for the target branch and explains when setup is missing, but it does not request permission to create or edit your repository rulesets.

Before starting, submit one coordinated Home Change so GitHub has seen the Composal check name. GitHub only offers recently reported checks in the required-check picker.

1. Open each affected repository in GitHub, then choose Settings → Rules → Rulesets and New branch ruleset.

2. Name the rule Composal coordinated Home landing, set Enforcement status to Active, and leave the bypass list empty unless your organization has an explicit exception policy.

3. Under Target branches, add the repository’s default branch, or add the exact target branch used by the Composal Change.

4. Enable Require status checks to pass, choose Add checks, search for Composal / coordinated landing, and select the result published by the Composal GitHub App. Then create the ruleset.

Repeat this for every GitHub repository that a coordinated Home Change can touch. GitHub Team and Enterprise organizations can instead use one organization ruleset that targets all of those repositories. Composal reads both repository and organization rules that apply to the target branch.

The next Composal coordination sync or pull-request event rechecks the effective rule. When every affected target branch requires the Composal check, the setup banner on the Change disappears. Ordinary pull requests receive a passing coordination check; only multi-repository Home Changes remain blocked for coordinated landing in Composal.

Why Composal does not configure this for you

GitHub’s write permission for repository administration covers much more than this one check. Keeping that permission out of the Composal App means your repository owners remain the only people who can change merge protections, bypass policy, and branch governance. Composal needs only read access to verify the rule and Checks write access to publish its own result.

For GitHub’s full ruleset controls and plan availability, see Creating rulesets for a repository.

Generic HTTP(S) Git

Import a generic Git source from a URL or local path. Add sync settings only when the source should keep participating in a two-way or configured sync workflow.

com import git https://git.example.com/team/repo.git \
  --org <org> --path apps/<slug> --virtual-repo <slug> --yes

Preview a direct generic import with --dry-run before adding --yes. The import flow is separate from day-to-day native Composal work; see source control for that workflow.

What Composal stores

Composal keeps the imported repository’s provider identity, selected branch, sync mode, and the baseline that lets a later sync reconcile external changes. GitHub connections additionally use the authorized App installation rather than a personal shell token.

Manual sync runs

Use the repository’s sync controls or CLI workflow to inspect and reconcile connected state. For submitted changes, use com sync to fetch the selected target and update the server review state. For materializing a GitHub project into a monorepo folder, use GitHub materialization.

If Settings → Sync shows Needs attention, review the error and select Retry Sync after addressing it. For blocked outgoing GitHub sync, this rechecks the current App permissions and remote branch before resuming the existing work. You do not need to reinstall an App that already has the required permissions. If the branch has changed unexpectedly, retry reports the conflict instead of overwriting it. The page refreshes while sync is waiting or running.