8000 Merge pull request #573 from github/update-1407283078 · sutt0n/developer.github.com@3b1fc23 · GitHub
[go: up one dir, main page]
Skip to content

Commit 3b1fc23

Browse files
author
hubot
committed
Merge pull request github#573 from github/update-1407283078
2 parents 1135768 + 6738bcf commit 3b1fc23

File tree

3 files changed

+184
-3
lines changed

3 files changed

+184
-3
lines changed

‎content/changes/2014-08-05-team-memberships-api.md‎

Lines changed: 40 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,40 @@
1+
---
2+
kind: change
3+
title: We're changing the way you add new members to your organization
4+
created_at: 2014-08-05
5+
author_name: jakeboxer
6+
---
7+
8+
Today, we're announcing a change to the way organization owners add new members to their organization.
9+
10+
Previously, if you were an organization owner, you could use the [add team member][add-team-member] endpoint to add any GitHub user to any team on your organization without any sort of approval from them. Now, we're increasing user security by sending [invitations][org-invitations] to users when they're added to teams on organizations that they aren't yet a part of.
11+
12+
With this change, if you use the [add team member][add-team-member] endpoint to add a user to a team and that user isn't already on another team in your organization, the request will fail.
13+
14+
### The new Team Memberships API
15+
16+
You should change all your [add team member][add-team-member] requests to use the new [add team membership][add-team-membership] endpoint. This new endpoint works exactly the same as the old one, with one important change: if the membership being added is for a user who is unaffiliated with the team's organization, that user will be sent an invitation via email.
17+
18+
Unlike the [add team member][add-team-member] endpoint, a successful request to the [add team membership][add-team-membership] endpoint does *not* guarantee that the user is now a member of the team. If you're trying to migrate to the new endpoint and need to know when a user has been successfully added (not just invited) to a team, please check out [TeamAddEvent][team-add-event].
19+
20+
### Preview period
21+
22+
We're making the new Team Memberships API (and the breaking changes to the [add team member][add-team-member] API) available today for developers to preview. During this period, we may change aspects of these endpoints. If we do, we will announce the changes on the developer blog, but we will not provide any advance notice.
23+
24+
While these new APIs are in their preview period, you'll need to provide the following custom media type in the `Accept` header:
25+
26+
application/vnd.github.the-wasp-preview+json
27+
28+
We expect the preview period to last 30-60 days. At the end of the preview period, the Team Memberships API will become an official component of GitHub API v3, as will the [add team member][add-team-member] API's breaking changes.
29+
30+
If you have any questions or feedback, please [get in touch with us][contact]!
31+
32+
[contact]: https://github.com/contact?form[subject]=Team+Memberships+API
33+
[org-invitations]: https://help.github.com/articles/adding-or-inviting-members-to-a-team-in-an-organization
34+
[add-team-member]: /v3/orgs/teams/#add-team-member
35+
[add-team-membership]: /v3/orgs/teams/#add-team-membership
36+
[get-team-member]: /v3/orgs/teams/#get-team-member
37+
[get-team-membership]: /v3/orgs/teams/#get-team-membership
38+
[remove-team-member]: /v3/orgs/teams/#remove-team-member
39+
[remove-team-member]: /v3/orgs/teams/#remove-team-membership
40+
[team-add-event]: /v3/activity/events/types/#teamaddevent

‎content/v3/orgs/teams.md‎

Lines changed: 132 additions & 3 deletions
1E71
Original file line numberDiff line numberDiff line change
@@ -122,8 +122,9 @@ must be a member of the team.
122122
## Add team member
123123

124124
In order to add a user to a team, the authenticated user must have
125-
'admin' permissions to the team or be an owner of the org that the team
126-
is associated with.
125+
'admin' permissions to the team or be an owner of the organization that the team
126+
is associated with, and the user being added must already be a member of at
127+
least one other team on the same organization.
127128

128129
PUT /teams/:id/members/:username
129130

@@ -145,19 +146,147 @@ If you attempt to add an organization to a team, you will get this:
145146
}]
146147
%>
147148

149+
If you attempt to add a user to a team and that user is not a member of at least
150+
one other team on the same organization, you will get this:
151+
152+
<%= headers 422 %>
153+
<%=
154+
json :message => "Validation Failed",
155+
:errors => [{
156+
:code => "unaffiliated",
157+
:field => :user,
158+
:resource => :TeamMember
159+
}]
160+
%>
161+
148162
## Remove team member
149163

150164
In order to remove a user from a team, the authenticated user must have
151165
'admin' permissions to the team or be an owner of the org that the team
152166
is associated with.
153-
NOTE: This does not delete the user, it just remove them from the team.
167+
NOTE: This does not delete the user, it just removes them from the team.
154168

155169
DELETE /teams/:id/members/:username
156170

157171
### Response
158172

159173
<%= headers 204 %>
160174

175+
## Get team membership
176+
177+
<div class="alert">
178+
<p>
179+
The Team Memberships API is currently available for developers to preview.
180+
During the preview period, the API may change without notice.
181+
Please see the <a href="/changes/2014-08-05-team-memberships-api/">blog post</a> for full details.
182+
</p>
183+
184+
<p>
185+
To access the API during the preview period, you must provide a custom <a href="/v3/media">media type</a> in the <code>Accept</code> header:
186+
<pre>application/vnd.github.the-wasp-preview+json</pre>
187+
</p>
188+
</div>
189+
190+
In order to get a user's membership with a team, the authenticated user must be
191+
a member of the team or an owner of the team's organization.
192+
193+
GET /teams/:id/memberships/:username
194+
195+
### Response if user has an active membership with team
196+
197+
<%= headers 200 %>
198+
<%= json(:active_team_membership) %>
199+
200+
### Response if user has a pending membership with team
201+
202+
<%= headers 200 %>
203+
<%= json(:pending_team_membership) %>
204+
205+
### Response if user has no membership with team
206+
207+
<%= headers 404 %>
208+
209+
## Add team membership
210+
211+
<div class="alert">
212+
<p>
213+
The Team Memberships API is currently available for developers to preview.
214+
During the preview period, the API may change without notice.
215+
Please see the <a href="/changes/2014-08-05-team-memberships-api/">blog post</a> for full details.
216+
</p>
217+
218+
<p>
219+
To access the API during the preview period, you must provide a custom <a href="/v3/media">media type</a> in the <code>Accept</code> header:
220+
<pre>application/vnd.github.the-wasp-preview+json</pre>
221+
</p>
222+
</div>
223+
224+
In order to add a membership between a user and a team, the authenticated user
225+
must have 'admin' permissions to the team or be an owner of the organization
226+
that the team is associated with.
227+
228+
If the user is already a part of the team's organization (meaning they're on at
229+
least one other team in the organization), this endpoint will add the user to
230+
the team.
231+
232+
If the user is completely unaffiliated with the team's organization (meaning
233+
they're on none of the organization's teams), this endpoint will send an
234+
invitation to the user via email. This newly-created membership will be in the
235+
"pending" state until the user accepts the invitation, at which point the
236+
membership will transition to the "active" state and the user will be added as a
237+
member of the team.
238+
239+
PUT /teams/:id/memberships/:username
240+
241+
### Response if user's membership with team is now active
242+
243+
<%= headers 200 %>
244+
<%= json(:active_team_membership) %>
245+
246+
### Response if user's membership with team is now pending
247+
248+
<%= headers 200 %>
249+
<%= json(:active_team_membership) %>
250+
251+
If you attempt to add an organization to a team, you will get this:
252+
253+
<%= headers 422 %>
254+
<%=
255+
json :message => "Validation Failed",
256+
:errors => [{
257+
:code => "org",
258+
:field => :user,
259+
:resource => :TeamMember
260+
}]
261+
%>
262+
263+
## Remove team membership
264+
265+
<div class="alert">
266+
<p>
267+
The Team Memberships API is currently available for developers to preview.
268+
During the preview period, the API may change without notice.
269+
Please see the <a href="/changes/2014-08-05-team-memberships-api/">blog post</a> for full details.
270+
</p>
271+
272+
<p>
273+
To access the API during the preview period, you must provide a custom <a href="/v3/media">media type</a> in the <code>Accept</code> header:
274+
<pre>application/vnd.github.the-wasp-preview+json</pre>
275+
</p>
276+
</div>
277+
278+
In order to remove a membership between a user and a team, the authenticated
279+
user must have 'admin' permissions to the team or be an owner of the
280+
organization that the team is associated with.
281+
NOTE: This does not delete the user, it just removes their membership from the
282+
team.
283+
284+
DELETE /teams/:id/memberships/:username
285+
286+
### Response
287+
288+
<%= headers 204 %>
289+
161290
## List team repos
162291

163292
GET /teams/:id/repos

‎lib/resources.rb‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -712,6 +712,18 @@ def fetch_content(key)
712712
"organization" => ORG
713713
})
714714

715+
TEAM_MEMBERSHIP = {
716+
"url" => "https://api.github.com/teams/1/memberships/octocat"
717+
}
718+
719+
ACTIVE_TEAM_MEMBERSHIP = TEAM_MEMBERSHIP.merge(
720+
"status" => "active"
721+
)
722+
723+
PENDING_TEAM_MEMBERSHIP = TEAM_MEMBERSHIP.merge(
724+
"status" => "pending"
725+
)
726+
715727
LABEL = {
716728
"url" => "https://api.github.com/repos/octocat/Hello-World/labels/bug",
717729
"name" => "bug",

0 commit comments

Comments
 (0)
0