Sync from GitHub

Keep your models on CommunityCAD in step with a GitHub repo. Link a repo, public or private, and every push updates your models: new folders become new models, changed files become new versions, and you never upload by hand again.

Sync from GitHub is rolling out. If Upload → Repo says it's coming soon, it isn't switched on for the site yet.

Linking a repo#

Go to Upload and choose Repo. It walks you through it:

1. Connect GitHub (the first time only). GitHub asks you to install the CommunityCAD app on your account or on an organisation, and to choose which repos it may see. Choose only the ones you want on CommunityCAD. You come straight back.
2. Repo: pick the repo, the branch to follow (usually main) and, optionally, a folder to link instead of the whole repo. If you're a member of a company on CommunityCAD, you can publish its models for your company: they appear under the company too, and everyone in it can manage the link.
3. What's in it: each folder with CAD files, with our guess: a model, a group, part of the model above it, or left out. Change anything that's wrong (see below).
4. Settings: one model per folder or one for everything, new models' visibility, and what happens when a folder is removed.
5. Link and sync. Choose whether to save your choices in the repo as communitycad.yml: by a pull request we open (recommended), by downloading the file, or not at all. Your choices apply from the first sync either way. The first sync starts right away, and the page shows it finishing.

Manage linked repos afterwards on your profile's GitHub tab: each repo's last sync, Sync now, Set up (the same choices again), Pause and Unlink.

To share more repos later, or fewer, change the app's settings on GitHub. A repo you stop sharing pauses its sync; sharing it again resumes it.

How a repo becomes models#

By default, every folder that directly holds CAD files is one model, and the folders above it become groups (the repo itself isn't one: its top folders are the top groups on your page):

acme-mounts/
├── README.md
├── LICENSE
├── motion/                  → a group, "Motion"
│   ├── nema17/              → a model, "NEMA 17 mount"
│   │   ├── README.md
│   │   ├── nema17.step
│   │   └── photo.png
│   └── linear/              → a group inside "Motion"
│       └── rail-clamp/      → a model
│           └── clamp.f3d
└── tools/build.py           → left out (not CAD)

Folders named for a format or a role belong to the model above them, so the common layout of one project with STL/ and STEP/ folders is one model, not two. These names count: stl, stls, step, cad, exports, files, print-files, images, renders, docs, drawings, models, 3d and a few more like them.

Each model's files are packed in the usual layout (see Organising your files):

The README is the model's page. Tables, headings and HTML (like <img width="400">) show as they do on GitHub, and relative links work: an image in the folder shows that photo, a link to a CAD file opens the model's Files tab at that file, a link to another model's folder opens its page, and #heading links jump within the page. Links to files outside the linked folder open on GitHub. If you edit the page on CommunityCAD, your edit stays until the README changes in the repo.

Hidden folders (starting with .), node_modules and files that aren't CAD, images or documents are left out.

What happens on a push#

Each push to the linked branch starts a sync of that commit. The whole page follows the repo: files, description, license, gallery photos and datasheets. Photos and datasheets you add by hand on CommunityCAD are left alone.

• A new folder becomes a new model.
• Changed files make a new version of their model. A push that changes nothing in a model leaves it alone. Changing a photo or a PDF updates the page without a new version.
• A renamed folder keeps its model, with the same page, downloads and comments, as long as its files didn't change in the same push.
• A removed folder follows your setting, below.

Pushes in quick succession sync once, with the latest commit. Press Sync now on the GitHub tab to sync without pushing. Edits you make on CommunityCAD (a title, tags, images) stay, unless your communitycad.yml sets that field.

When a folder is removed#

You choose, when you link the repo, in the setup walkthrough, or in communitycad.yml:

The setup walkthrough#

You go through it when you link a repo, and again any time from Set up next to a linked repo on your profile's GitHub tab. It's optional; skip it if the folders already look right.

1. What's in it: each folder with CAD files, with our guess: a model, a group, part of the model above it, or left out. Change any of them and their titles.
2. Settings: one model per folder or one for everything, new models' visibility, and what happens when a folder is removed.
3. Save: we open a pull request on your repo that adds communitycad.yml, on a new branch. Nothing changes in your repo until you merge it. If you'd rather not, download the file and add it yourself. Your choices apply from the next sync, before the file is merged; once the repo has its own communitycad.yml, that file is used instead.

If you only ignore folders, rename groups or change settings, new folders keep becoming models by themselves. If you choose which folders are models, the file lists them, and new folders need adding to it (or run the walkthrough again).

communitycad.yml#

Put communitycad.yml at the top of the linked folder. When it's there, it always wins. Every setting is optional:

version: 1
title: Acme mounts              # the repo's name on your GitHub tab
layout: folders                 # or single: the whole folder is one model
on_remove: follow               # or notify, keep
visibility: public              # new models; or private
license: MIT                    # for models without a LICENSE file
tags: [mounts]                  # added to every model
sourcing: own                   # auto, own or none: see Sourcing below
ignore:                         # left out entirely
  - drafts/**
  - "*.bak"
groups:                         # titles and descriptions for folders
  motion: {title: Motion, description: Motor and rail mounts}

To say exactly which models there are, list them. Each needs an id that never changes, so moving its folder keeps the model:

models:
  - id: nema17-mount
    path: motion/nema17
    title: NEMA 17 mount
    description: Holds a NEMA 17 motor on 2020 extrusion.
    tags: [nema17, 2020]
    visibility: public
    license: CC-BY-4.0
    group: motion               # default: the folder above path
    sourcing: own               # this model only
    sources:                    # where to buy it, shown on its Sourcing tab
      - {url: "https://www.mcmaster.com/91290A113/", label: "91290A113, pack of 100"}
    files: ["*.step", "exports/*.stl"]   # default: everything in the folder
  - id: whole-kit
    path: .                     # the linked folder itself

With a models list, only those are models. A file belongs to the deepest listed model whose folder holds it, so a model inside another model's folder doesn't share its files.

Sourcing is how a model's Sourcing tab (where to buy the parts it uses) works: auto lets CommunityCAD find the parts and add them with Amazon affiliate links, which support CommunityCAD at no cost to buyers; own shows the links you add, exactly as you enter them; none means no Sourcing tab. Like every setting here it's applied on every sync, and a model's own value wins over the top one. Without it, new models start with your account's default (on your profile's settings), or you're asked on each model.

Sources (in a models list) are a model's Sourcing tab: each has a url (starting https://) and a label saying what it is, like the pack size or part number, up to 120 characters; up to 20 per model, shown in order. The repo keeps them: every sync makes the list match, and it can't be edited on the site while the file lists them. Take sources out of the file and the list is yours to edit on the site again.

Licenses you can name: MIT, Apache-2.0, GPL-3.0, BSD-3-Clause, CC-BY-4.0, CC-BY-SA-4.0 and CC0-1.0. For any other license, add a LICENSE file instead.

If the file has a mistake, the sync stops before changing anything, and the GitHub tab lists every problem with its line number, like:

communitycad.yml has problems:
- Line 3: `on_remove` must be follow, notify or keep (it says `delete`).
- Line 9: `id: bracket` is used twice (also on line 5); each model needs its own.

Limits#

There's no limit on the repo's size. The first sync of a big repo can take a while (hours for tens of thousands of models); the GitHub tab shows how far it has got, and the site stays up meanwhile. After that each push fetches only the files that changed, and files matched by ignore are never fetched.

Git LFS: files stored in Git LFS sync as the real files. Each is downloaded once, when it's new or changed; those downloads count toward your GitHub account's LFS bandwidth. An LFS file over 100 MB is left out and listed, like any other.

Private repos and what CommunityCAD can access#

• The app sees only the repos you choose, and only their files and basic details.
• It reads. It writes only when you ask it to open the setup pull request, and then only to a new branch of its own. GitHub calls this permission "contents: write", and it's what makes the pull request possible.
• Files from a private repo are copied into CommunityCAD, so a private repo can back a public model. Each model's visibility is yours to choose; check you have the right to publish what you sync.
• To stop syncing, Unlink the repo on the GitHub tab (its models stay as they are), or remove the app on GitHub.

Models imported from your GitHub#

If we imported your public CAD repos before you joined (see Companies and imported models), your profile offers to claim them or take them down. Once claimed, the GitHub tab lists them under Your models from GitHub: press Keep synced and the model follows your repo from then on, keeping its page, downloads and history.

When something goes wrong#

The GitHub tab shows each repo's last sync and its error, in plain words:

Still stuck? Contact us.