Skip to content

Commit 9f01b3b

Browse files
glaubinixglaubinix
authored
Merge pull request #108 from packagist/suborganization-rename
Suborganization: rename subrepositories and adjust API examlpes
2 parents dc6ecb6 + 3bc2943 commit 9f01b3b

File tree

5 files changed

+179
-179
lines changed

5 files changed

+179
-179
lines changed

‎docs/composer-authentication.md

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -8,15 +8,15 @@ Three different types of authentication tokens can be used to access Private Pac
88

99
### User access token
1010
Every user has their own token that they can access either on the profile page or on the overview page of their organizations.
11-
The token grants the user access to all organizations and subrepositories they are a member of.
11+
The token grants the user access to all organizations and suborganizations they are a member of.
1212

1313
### Organization authentication tokens
1414
Admins and owners of an organization can create additional tokens on the organization settings page.
1515
Organization authentication tokens are ideal for automated systems like your CI environment or deployments. A token's access can be restricted to any set of packages which any of the organization's teams has access to.
1616

17-
If your organization uses subrepositories then you can also create additional tokens in subrepositories.
18-
Tokens created in the organization settings do not grant you access to any of your subrepositories and tokens created in
19-
a subrepository only grant you access to the subrepository the token was created in.
17+
If your organization uses suborganizations then you can also create additional tokens in suborganizations.
18+
Tokens created in the organization settings do not grant you access to any of your suborganizations and tokens created in
19+
a suborganization only grant you access to the suborganization the token was created in.
2020

2121
#### Read-only vs update tokens
2222
There are two kinds of organization authentication tokens: read-only and update tokens.

‎docs/security-monitoring.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -19,7 +19,7 @@ Additional branches to be monitored can be selected on the package page.
1919

2020
Security monitoring can be disabled for individual project packages on the package security page or for all projects
2121
on the organization’s security settings page.
22-
Organizations using subrepositories have the option to disable security monitoring for individual subrepositories.
22+
Organizations using subroganizations have the option to disable security monitoring for individual suborganizations.
2323

2424
### Configuring Notifications
2525
Every user receives security notifications by email for all projects they have access to by default.

‎docs/setup-ci-cd.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -12,7 +12,7 @@ COMPOSER_AUTH='{"http-basic": {"repo.packagist.com": {"username": "token", "pass
1212
```
1313

1414
Note that read-only tokens are recommended for CI/CD where you'll be running composer install commands with an existing composer.lock file. Read-only tokens are not suitable to run `composer update` as they do not create new mirrored packages. In case you have automated tasks that run package updates, make sure to use tokens with update access.
15-
Read-only tokens don't count as users in your Private Packagist organization, while update tokens will be billed like an additional user account. Read-only tokens can only access packages in your organization. Read-only tokens created in a subrepository will only access packages in the respective subrepository.
15+
Read-only tokens don't count as users in your Private Packagist organization, while update tokens will be billed like an additional user account. Read-only tokens can only access packages in your organization. Read-only tokens created in a suborganization will only access packages in the respective suborganization.
1616

1717
## Instructions for CI/CD services
1818

‎docs/setup-suborganization.md

Lines changed: 173 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,173 @@
1+
# Private Packagist Suborganizations
2+
##
3+
4+
Suborganizations are additional Composer repositories in an organization with their own URL, authentication tokens, and a separate list of packages.
5+
6+
You can select which mirrored third-party repositories, shared organization packages, and credentials can be used in each suborganization and which users should have access to a suborganization. Synchronization of packages with GitHub, Bitbucket or GitLab can be set up for a suborganization separately from the organization's synchronizations.
7+
8+
## When to use suborganizations?
9+
10+
Suborganizations are an optional feature which helps you separate the packages and configuration for different Composer projects. The following are some of the use cases for which
11+
we recommend using suborganizations. You can also begin using Private Packagist without suborganizations and add them later.
12+
13+
### Agencies: Managing client projects
14+
15+
When working on client projects you may have packages which should only be available to a particular client e.g.
16+
a design you built, or a third party package that you purchased. Suborganizations allow you to add these packages only
17+
to the client's Composer repository while other client projects will remain unable to install them. This is particularly useful if your clients run Composer commands themselves to prevent them from installing packages they should not have access to.
18+
19+
In case your clients require access to Private Packagist you can invite them as collaborators to the suborganization. They won't have access to your organization but will be able to work with the suborganization they were invited to.
20+
21+
### Composer projects using different major versions of a framework
22+
23+
Several frameworks like Magento and Drupal use a different set of packages for each major framework version.
24+
Drupal, for instance, uses a different mirrored third-party repository for each major version from where packages can be installed.
25+
Each of these repositories may contain packages with the same name that only work with a particular major framework version.
26+
27+
Suborganizations can help separate your packages for such projects. Start with one suborganization for each major Drupal version, e.g.
28+
one for Drupal 7 and one for Drupal 8. Then change your composer.json in all Composer projects using Drupal 7 and 8 to load packages from the respective suborganization's URL. Now you will never accidentally install a package for the wrong Drupal version in one of your Composer projects.
29+
30+
## Setting up a suborganization in Private Packagist
31+
32+
Organization owners and admins can create suborganizations on the suborganizations page via the "Create suborganization" button.
33+
On the settings page of an individual team you can grant all members of a team permission to create suborganizations.
34+
35+
Alternatively, you can create suborganizations using our API through the [API client](https://github.com/packagist/private-packagist-api-client) with the following code snippet:
36+
37+
```
38+
<?php
39+
40+
require_once __DIR__ . '/vendor/autoload.php';
41+
42+
$suborganizationName = 'company-blog';
43+
44+
$client = new \PrivatePackagist\ApiClient\Client();
45+
$client->authenticate('api-token', 'api-secret');
46+
$customer = $client->suborganizations()->create($suborganizationName);
47+
```
48+
49+
### Setting up mirrored third party repositories and credentials
50+
51+
On the suborganization settings page you can configure the mirrored third-party repositories and credentials that can be used in
52+
the suborganization.
53+
Accessing the mirrored third-party repository settings page allows you to either add existing mirrors
54+
from the organization or configure additional mirrored third-party repositories for the suborganization only. The same applies for credentials.
55+
56+
Your organization settings page allows you to see in which suborganizations a specific mirrored third-party repository
57+
or credential is available. You can configure them to be automatically added to every new suborganization which
58+
you create to facilitate the setup of new suborganizations.
59+
60+
Alternatively, mirrored third-party repositories can be added to a suborganization via our API using our [API client](https://github.com/packagist/private-packagist-api-client) with the following code snippet:
61+
62+
```
63+
<?php
64+
65+
require_once __DIR__ . '/vendor/autoload.php';
66+
67+
$suborganizationName = 'company-blog';
68+
69+
$client = new \PrivatePackagist\ApiClient\Client();
70+
$client->authenticate('api-token', 'api-secret');
71+
72+
$mirroredRepositories = $client->mirroredRepositories()->all();
73+
// Find the id of the mirrored third-party repository you are looking for
74+
$mirroredRepositoryId = array_pop($mirroredRepositories)['id'];
75+
76+
$mirroredRepositoryData = [
77+
'id' => $mirroredRepositoryId,
78+
'mirroringBehavior' => 'add_on_use',
79+
];
80+
81+
$client->suborganizations()->mirroredRepositories()->add($suborganizationName, [$mirroredRepositoryData]);
82+
```
83+
84+
### Adding packages
85+
86+
Existing packages can be shared into the suborganization via "Add Package" -> "Organization Packages".
87+
Select all necessary packages and add them to the suborganization, you can select to add their dependencies too. If you need to create new packages in a suborganization you can add them using the "Add Package" dialog and the previously set up credentials.
88+
89+
Mirrored packages will automatically be added to your suborganization on use via composer commands. We do not recommend manually adding them to your suborganization.
90+
91+
Alternatively, packages can be added via our API using our [API client](https://github.com/packagist/private-packagist-api-client) with the following code snippet:
92+
93+
```
94+
<?php
95+
96+
require_once __DIR__ . '/vendor/autoload.php';
97+
98+
$suborganizationName = 'company-blog';
99+
$url = 'https://github/acme/company-blog-design';
100+
101+
$client = new \PrivatePackagist\ApiClient\Client();
102+
$client->authenticate('api-token', 'api-secret');
103+
$client->suborganizations()->packages()->createVcsPackage($suborganizationName, $url);
104+
```
105+
106+
### Granting members access
107+
108+
Permissions in suborganizations are managed via teams, the same way permissions are managed in your organization.
109+
You can add teams to a suborganization and all members of that team will be granted access to the suborganization.
110+
Team membership changes e.g. through a synchronization will automatically be applied to suborganizations as well.
111+
112+
One notable difference in suborganizations is that all members automatically have access to all packages inside a suborganization.
113+
You do not have to manually grant access to packages.
114+
115+
Alternatively, teams can be added to a suborganization via our API using our [API client](https://github.com/packagist/private-packagist-api-client) with the following code snippet:
116+
117+
```
118+
<?php
119+
120+
require_once __DIR__ . '/vendor/autoload.php';
121+
122+
$suborganizationName = 'company-blog';
123+
124+
$client = new \PrivatePackagist\ApiClient\Client();
125+
$client->authenticate('api-token', 'api-secret');
126+
127+
$teams = $client->teams()->all($suborganizationName, $url);
128+
// find id of team to be added
129+
$teamId = array_pop($teams)['id'];
130+
131+
$team = [
132+
'id' => $teamId,
133+
'permission' => 'view',
134+
];
135+
136+
$client->suborganizations()->addOrEditTeams($suborganizationName, [$team]);
137+
```
138+
139+
### Granting external collaborators access to a suborganization
140+
141+
Working on a Composer project with external developers might sometimes require that those developers get access to a suborganization
142+
to make sure they can run composer install and update and help manage the project's dependencies. Adding them as suborganization
143+
collaborators will only grant them access to selected suborganizations and not give them access to you your Private Packagist organization.
144+
145+
You can invite via email suborganization collaborators on the suborganization's team page via the "Manage Collaborators" button.
146+
147+
148+
## Setting up CI / CD environments
149+
150+
We recommend that you create authentication tokens for your CI / CD environments and do not use your personal authentication token on automated systems.
151+
152+
You can create authentication tokens on the settings page of the suborganization page under authentication tokens.
153+
Please beware that tokens created on the organization's settings page will only have access to the organization's Composer repository
154+
and tokens created in a suborganization will only have access to that specific suborganization's Composer repository.
155+
156+
Alternatively, authentication tokens can be created via our API using our [API client](https://github.com/packagist/private-packagist-api-client) with the following code snippet:
157+
158+
```
159+
<?php
160+
161+
require_once __DIR__ . '/vendor/autoload.php';
162+
163+
$suborganizationName = 'company-blog';
164+
165+
$client = new \PrivatePackagist\ApiClient\Client();
166+
$client->authenticate('api-token', 'api-secret');
167+
168+
$tokenData = [
169+
"description" => "Blog deploy token",
170+
"access" => "read"
171+
];
172+
$token = $client->suborganizations()->createToken($suborganizationName, $tokenData);
173+
```

0 commit comments

Comments
 (0)