Publish a collection to GitHub

Before you begin

• Open Collections Desktop or Collection Manager is available to you.
• You have internet access.
• You have a collection ready to publish, or you are ready to create one.
• You have a GitHub account, or you are willing to create one.

Helpful way to think about the setup:

• GitHub account = who owns the repository.
• Public repository = where the published collection files live.
• Personal Access Token (PAT) = the permission token Open Collections uses to publish without using your password.
• Open Collections connection = the saved destination configuration inside the app.
• Publish = upload or update collection files in that repository.
• Collection URL = the web address where people can open the published collection.

1. Create a GitHub account

1. Open GitHub.
2. Choose the sign-up option and create your account.
3. Verify your email address if GitHub asks you to do that.
4. Sign in to your new or existing account.

You only need one account. That account will usually own the repository you publish to unless your organization gives you access to a shared organization account.

2. Create a public repository

1. In GitHub, create a new repository under your account or organization.
2. Choose a simple repository name such as my-collections, open-collections-site, or collections-publisher.
3. Set the repository visibility to Public.
4. Create the repository.

A public repository matters because the published collection files need to be available for public web access.

If your organization has a technical lead or web administrator, that person may already have created this repository for you. In that case, ask them for the repository owner name, repository name, branch, and path to use in Open Collections.

3. Create a GitHub Personal Access Token (PAT)

1. While signed in to GitHub, open your account settings.
2. Look for Developer Settings.
3. Look for Personal Access Tokens.
4. Create a new token.
5. Give it a clear label such as Open Collections publish.
6. Choose an expiration date that fits your organization’s security policy.
7. Grant the minimum repository permissions needed to update repository contents.

The exact labels may vary slightly in GitHub over time. If a screen looks a little different, look for the Personal Access Token area inside Developer Settings and choose the option that allows repository content updates.

This token lets Open Collections publish on your behalf without using your GitHub password.

Important: copy the token as soon as GitHub shows it. GitHub may only show the full token once.

Keep it safe: store the token in a secure password manager or approved secure note. Do not paste it into public documents, screenshots, emails, or files that will be committed to a repository.

4. Connect the repository in Open Collections Desktop / Collection Manager

In Open Collections, open the area where you add or configure a publish destination. In the current preview interface this is typically the host setup flow: Add a host → Remote host → Git repository. The exact labels may vary slightly as the app evolves.

1. Open the app and go to the publish destination, repository, or host setup area.
2. Choose the GitHub connection option.
3. Enter the repository details and your PAT.
4. Save or add the host/destination.

Values you will usually enter:

• Repository owner: the GitHub username or organization name.
• Repository name: the repository you created.
• Branch: usually main.
• Publish path or folder path: use /collections/ as the recommended default.
• PAT or access token: the token you copied from GitHub.

Recommended example:

• Owner: username
• Repository: my-collections
• Branch: main
• Publish path: /collections/

The recommended neutral web path is /collections/. Some organizations may instead use /opencollections/ or /webcollections/, but /collections/ is the best default unless your organization already has another convention.

If your app screen uses the label Folder path rather than Publish path, enter the same idea there: the folder inside the repository where published collections should be written.

5. Publish your first collection

1. Create a new collection or open an existing one in Open Collections.
2. Fill in the basic collection metadata such as title, description, and publisher.
3. Add items, records, or media references.
4. Save your local work.
5. Choose Publish.
6. Choose the GitHub destination you configured.
7. Confirm the publish action.

In simple terms, Open Collections uploads or updates the collection files in the GitHub repository you connected.

For many users, the first successful publish is the moment when a local working collection becomes a web collection that can be reopened and shared.

6. Open the published collection in the browser

After publishing, the collection should be reachable through the website or hosting setup connected to that repository.

Common examples:

• https://your-site.example/collections/your-collection-slug/
• https://username.github.io/repo-name/collections/your-collection-slug/

The exact URL depends on how that repository is hosted on the web. The expected path pattern is usually /collections/....

Some setups may instead use /opencollections/... or /webcollections/.... If you are unsure, ask the person who configured the hosting or look at the public base URL used by your organization.

A simple placeholder example is:

https://username.github.io/repo-name/collections/your-collection-slug/

If your collection does not open immediately, wait a short time and refresh. Some hosting systems take a little time to update after files are published.

Troubleshooting

• You did not copy the PAT when GitHub created it: create a new token and copy it immediately.
• The PAT does not have enough permission: create or update a token so it can update repository contents.
• The repository owner or repository name is wrong: check the GitHub URL carefully and re-enter the values.
• The branch is wrong: most repositories use main, but some teams use a different branch.
• The publish path is wrong: confirm whether your team expects /collections/, /opencollections/, /webcollections/, or another folder path.
• The repository is private: if public web hosting is expected, confirm that the repository or its hosting output is public.
• Publishing succeeded but nothing is visible on the web: the repository may be receiving files correctly, but the public hosting for that repository may not be configured yet.
• The files are there but the website looks out of date: wait a little longer and refresh because some hosting systems update with a short delay.

Admin or team setup note

In some organizations, a technical or admin person prepares the publish destination once. They may create the repository, set the branch and path, connect hosting, and provide a ready-to-use destination inside Open Collections.

When that setup exists, normal collection users often only need to choose the prepared destination and publish. This is usually the easiest and safest model for team workflows.

What success looks like

When everything is set up, you should have:

• a GitHub account
• a public GitHub repository
• a PAT stored safely
• a saved GitHub destination in Open Collections
• a published collection in that repository
• a browser URL that opens the collection on the web

That full path gives you a repeatable publishing workflow: edit locally, publish to GitHub, and share the collection URL.