Skip to content

Add more details to Synchronizations page #118

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 4 commits into from
Jan 27, 2025
Merged

Add more details to Synchronizations page #118

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
feeddd2
Move the description of synchronizations to a separate page
stevenrombauts Jan 27, 2025
b124641
Apply suggestions from code review
stevenrombauts Jan 27, 2025
cb62b7f
Update docs/synchronizations-faq.md
stevenrombauts Jan 27, 2025
fc78ad9
Still mention the Synchronization features on the OAuth Integrations …
stevenrombauts Jan 27, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
79 changes: 71 additions & 8 deletions docs/synchronizations-faq.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,16 +1,79 @@
# Synchronization FAQ
##
# Synchronizations
## Synchronization of users, teams, permissions and repositories

Synchronizations allow you to keep packages, teams, their members, and access permissions in sync with your code hosting platform, e.g. GitHub, GitLab or Bitbucket.
To simplify the initial setup and maintenance of a Private Packagist organization, we offer optional synchronization for GitHub organizations,
Bitbucket workspaces and GitLab groups. This synchronization keeps teams, their members, and access permissions in sync.
So you only need to manage users and permissions in a single place.

## What happens if you promote a synchronization to a primary synchronization?
Apart from synchronizing teams, users, and permissions, setting up the synchronization will simplify the addition of new packages
to your Composer repository. When you create a **new repository** on GitHub, Bitbucket, or GitLab, it will be **added as a
Composer package automatically** if it contains a _composer.json_ file. If you’d like to add existing repositories as packages,
you can do so with the click of a button on the Packages tab in your organization.

**Update web hooks** notifying Packagist of new code pushes will be installed in the background, and **credentials to access
the package** will be **configured automatically**.

## Getting started

You can log into Private Packagist using an account on github.com, Bitbucket.org, or GitLab.com with the relevant [OAuth integration](integration-github-bitbucket-gitlab.md)
If you already have an account you can connect these services to your existing account on your [profile page](https://packagist.com/profile).

You can then either create a new organization directly synchronized with a GitHub organization, Bitbucket workspace or a GitLab group,
or you can enable synchronization for an existing Organization in _Settings_.

![Synchronization](/Resources/public/img/docs/features/Sync-20241218.png)

## Supported providers

### GitHub
* Synchronization:
* Keeps teams, their members, and access permissions in sync with your GitHub organization
* Code Credentials: GitHub App or GitHub API Token
* Webhooks: Code changes, releases, created repositories, team creation or member changes
Comment on lines +31 to +32
Copy link
Contributor Author

@stevenrombauts stevenrombauts Jan 27, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think this (Code Creds/Webhooks) is also relevant on this page, but kept it in place on the OAuth Integrations page too. So it's duplicated, but I think we should mention it on both locations. Thoughts?

Copy link
Member

@glaubinix glaubinix Jan 27, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Makes sense to have it in both place but I would also keep the Synchronization: section on the integration page. This makes it easier to compare which features are available for which integration


### GitHub Enterprise Server
* Synchronization:
* Keeps team members and access permissions in sync with your GitHub Enterprise organizations
* Code Credentials: GitHub API Token
* Webhooks: Code changes, releases, created repositories, team creation or member changes

### Bitbucket Cloud (bitbucket.org)
* Synchronization:
* Keeps groups, their members, and access permissions in sync with your Bitbucket workspace
* Code Credentials: Bitbucket API Key or Bitbucket App Password
* Webhooks: Code changes and releases

### Bitbucket Data Center / Server
* Synchronization:
* Keeps users and access permissions in sync with your Bitbucket Server projects
* Individual collaborators aren't supported
* Code Credentials: personal access token which are available since Bitbucket Server 5.5 or username and password for older versions
* Webhooks: Code changes and releases

#### GitLab
* Synchronization:
* Keeps teams, their members, and access permissions in sync with your GitLab groups
* Individual collaborators aren't supported
* Code Credentials: GitLab API token
* Webhooks: Code changes and releases

#### GitLab Self-Managed
* Synchronization:
* Keeps teams, their members, and access permissions in sync with your GitLab groups
* Individual collaborators aren't yet supported
* Code Credentials: GitLab API Token
* Webhooks: Code changes and releases

## Frequently asked questions

### What happens if you promote a synchronization to a primary synchronization?

Synchronized Private Packagist organizations automatically have all admins and owners of the remote organization of the primary synchronization assigned to the admins and owners teams in Private Packagist. Admins and owners of additional synchronized remote organizations are not added to the admins or owners teams in Private Packagist.

When promoting a synchronization to primary, admins and owners of the corresponding remote organization will now be the sole members of the admins and owners teams on Private Packagist.
So keep in mind that if you switch the primary synchronization to a different service (e.g. from GitHub to Bitbucket), all admins and owners who do not have their user accounts connected to the new service yet (Bitbucket in the example) will lose admin/owner access to the Private Packagist organization. To restore their access, the users have to connect their account to the new service on the profile page.

## How to migrate a synchronization from GitHub to Bitbucket?
### How to migrate a synchronization from GitHub to Bitbucket?

1. Add a new synchronization with your Bitbucket workspace.
2. Delete the packages that were created by the GitHub synchronization. You can filter by the GitHub synchronization on the package list page and then you can delete the packages from that list.
Expand All @@ -19,19 +82,19 @@ So keep in mind that if you switch the primary synchronization to a different se

You can follow the same steps above in case you want to migrate from Bitbucket to GitLab or the other way around.

## How to migrate from one organization to another one in GitHub?
### How to migrate from one organization to another one in GitHub?

1. Add a new synchronization with the new GitHub organization.
2. On GitHub, you can transfer the packages from the old organization to the new one.
3. In case the old synchronization was primary, you need to promote the new synchronization to primary otherwise you won't be able to delete the old one. After verifying that the new synchronization successfully ran you can remove the old synchronization with GitHub. Please refer to ["What happens if you promote a synchronization to a primary synchronization?"](#what-happens-if-you-promote-a-synchronization-to-a-primary-synchronization) for more details about promoting a synchronization to primary.

## How to migrate from one workspace to another one in Bitbucket?
### How to migrate from one workspace to another one in Bitbucket?

1. Transfer your repositories in Bitbucket from the old workspace to the new one.
2. Create a new synchronization with the new Bitbucket workspace.
3. In case the old synchronization was primary, you need to promote the new synchronization to primary. Otherwise you won't be able to delete the old synchronization. After verifying that the new synchronization successfully ran, you can remove the old synchronization with Bitbucket. Please refer to ["What happens if you promote a synchronization to a primary synchronization?"](#what-happens-if-you-promote-a-synchronization-to-a-primary-synchronization) for more details about promoting a synchronization to primary.

## How to migrate from one group to another one in GitLab?
### How to migrate from one group to another one in GitLab?

1. Create a new synchronization with the new GitLab workspace.
2. Transfer your repositories in GitLab from the old group to the new one.
Expand Down
10 changes: 1 addition & 9 deletions features/integration-github-bitbucket-gitlab.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,18 +3,10 @@

Composer has broad support for version control systems, code hosting platforms and authentication protocols. As a consequence **Private Packagist is compatible with all the same systems and platforms**, namely Git, Mercurial or Subversion using SSH access, HTTP Basic Auth over SSL, or their native protocols.

To simplify the initial setup and maintenance of a Private Packagist account, we offer optional synchronization for GitHub organizations, Bitbucket workspaces and GitLab groups. This **integration keeps teams, their members, and access permissions in sync** with a matching GitHub organization. So you only need to manage users and permissions in a single place.
To simplify the initial setup and maintenance of a Private Packagist account, we offer optional [synchronization](../docs/synchronizations-faq.md) for GitHub organizations, Bitbucket workspaces and GitLab groups.

You can log into Private Packagist using an account on github.com, Bitbucket.org, or GitLab.com. If you already have an account you can connect these services to your existing account on your [profile page](https://packagist.com/profile).

You can then either create a new organization directly synchronized with a GitHub organization, Bitbucket workspace or a GitLab group, or you can enable synchronization for an existing Organization in _Settings_.

![Synchronization](/Resources/public/img/docs/features/Sync-20241218.png)

Apart from synchronizing teams, users, and permissions, setting up the integration will simplify the addition of new packages to your Composer repository. When you create a **new repository** on GitHub, Bitbucket, or GitLab, it will be **added as a Composer package automatically** if it contains a _composer.json_ file. If you’d like to add existing repositories as packages, you can do so with the click of a button on the Packages tab in your organization.

**Update web hooks** notifying Packagist of new code pushes will be installed in the background, and **credentials to access the package** will be **configured automatically**.

## Integrations

Private Packagist integrates with the following systems:
Expand Down