Nanoc has[some nice documentation](http://nanoc.ws/docs/tutorial/) to get you started. Though if you're mainly concerned with editing or adding content, you won't need to know much about nanoc.

[nanoc]:http://nanoc.stoneship.org/

[nanoc]:http://nanoc.ws/

You can specify terminal blocks with`pre.terminal` elements. (It'd be

nice ifMarkdown could do this more cleanly.)

You can specify terminal blocks with`pre.terminal` elements. (It'd be nice if

Markdown could do this more cleanly.)

<preclass="terminal">

author_name:jakeboxer

**Update:2014-09-30:** In response to feedback from developers, we're delaying the breaking change to the["Add team member" API][add-team-member] until Monday,**October 6, 2014**. The change will go into effect for all requests on that date.

**UPDATE (2014-09-30):** In response to feedback from developers, we're delaying the breaking change to the["Add team member" API][add-team-member] until Monday,**October 6, 2014**. The change will go into effect for all requests on that date.

Starting October 6, if you use[the "Add team member" API][add-team-member] to add a user to a team and that user isn't already on another team in your organization, the request will fail. To avoid this, be sure to use the[the "Add team membership" API][add-team-membership].

"sha": "deadbeef",

"ref": "master",

"task": "deploy",

"name": "my-org/our-app",

"environment": "production",

"payload": {…},

"description": "Deploying master",

"sha": "deadbeef",

"ref": "master",

"task": "deploy",

"name": "my-org/our-app",

"environment": "production",

"payload": {…},

"description": "Deploying master",

kind:change

title:The Deployments API is official

created_at:2014-11-25

author_name:atmos

We're happy to announce that the[Deployments API][docs] is officially part

of GitHub API v3. We now consider it stable for production use.

Thanks to everyone who provided feedback during the preview period. We got

some great feedback, and hope this feature helps you build the tools you

need to make GitHub the best place to ship exactly the way you want.

If you used the Deployments API during the preview period, you needed to

provide a custom media type in the`Accept` header:

Now that the preview period has ended, you no longer need to pass this custom

media type.

Instead, we[recommend][media-types] that you specify`v3` as the version in the

`Accept` header:

We'll never be done listening to you! As always, please don't hesitate to

[share your feedback][feedback].

[docs]:/v3/repos/deployments

[media-types]:/v3/media

[feedback]:https://github.com/contact?form[subject]=Deployments+API

kind:change

title:Preview the New Organization Webhooks API

created_at:2014-12-03

author_name:jdpace

Today we're very excited[to announce Organization Webhooks][dotcom-blog-post].

Organization Webhooks allow you to subscribe to events that happen across an

entire organization.

In addition to being able to subscribe to the existing repository oriented

events across an organization, we're also adding some new events which are

exclusive to organization webhooks. The new[`repository`

event][repository-event] allows you to receive webhook payloads when a new

repository is created. By subscribing to the[`membership`

event][membership-event], you'll be notified whenever a user is added or

removed from a team.

We’re making this new API for Organization Webhooks available today[for

developers to preview][docs-preview]. The preview period will allow us to[get

your feedback][contact] before declaring the Organization Webhooks API final.

We expect the preview

period to last for roughly 30-60 days.

As we discover opportunities to improve the API during the preview period, we

may ship changes that break clients using the preview version of the API. We

want to iterate quickly. To do so, we will announce any changes here (on the

developer blog), but we will not provide any advance notice.

At the end of preview period, the Organization Webhooks API will become an

official component of GitHub API v3. At that point, the new Organization

Webhooks API will be stable and suitable for production use.

We hope you’ll take it for a spin and[send us your feedback][contact].

[dotcom-blog-post]:https://github.com/blog/1933-introducing-organization-webhooks

[repository-event]:/v3/activity/events/types/#repositoryevent

[membership-event]:/v3/activity/events/types/#membershipevent

[docs]:/v3/orgs/hooks/

[docs-preview]:/v3/orgs/hooks/#preview-period

[contact]:https://github.com/contact?form[subject]=Organization+Webhooks

kind:change

title:Preview the upcoming organization permission changes

created_at:2014-12-08

author_name:jakeboxer

**UPDATE (2014-12-12):** The[List your organizations][list-your-organizations] API is now included in this preview as well.

We have some upcoming changes that will affect the way organization members and repositories are managed. The most important changes are:

- The Owners team will no longer be special.

- The[List your repositories][list-your-repos] API will include organization-owned repositories.

- The[List user organizations][list-user-organizations] API will only include public organization memberships.

- The[List your organizations][list-your-organizations] API will require`user` scope or`read:org` scope.

Currently, members of your Owners team are administrators of your organization. Soon, your Owners team will become a totally normal team. Adding and removing Owners team members won't change their administrator status anymore. Instead, you'll be able to directly grant admin permissions to your organization's members without adding them to any special teams.

We won't delete your Owners team, but you'll be able to delete or rename it yourself if you want. Organizations created after the change won't have an Owners team.

In preparation for this change to the Owners team, we're releasing a few new APIs. You'll be able to use these APIs to manage organization admins without relying on the Owners team.

To add a new organization admin, use the new[Add or update organization membership][add-org-membership] endpoint, specifying a role of`"admin"` in the request body. This replaces adding or inviting people to the Owners team.

To remove someone from the organization role but keep them as a member of their teams, use the new[Add or update organization membership][add-org-membership] endpoint, specifying a role of`"member"` in the request body. This replaces removing people from the Owners team.

To get a list of all your organization's admins, use the[Organization members list][list-org-members] endpoint, specifying a role of`"admin"` in the query string. This replaces listing the members of the Owners team.

To check if a given user is an organization admin, use the new[Get organization membership][get-org-membership] endpoint. If the returned`"role"` attribute is set to`"admin"` and the returned`"state"` attribute is set to`"active"`, the user is an organization admin. This replaces checking if a user is on the Owners team.

Currently, the[List your repositories][list-your-repos] API only returns repositories that are owned by users, not by organizations. If you want a list of*all* the repositories that the authenticated user has access to, you need to use multiple API methods.

Soon, this API will include all repositories that the authenticated user has access to (whether they're owned by a user or by an organization).

Many apps use the[List your repositories][list-your-repos] API in conjunction with the[List your organizations][list-your-orgs] and[List organization repositories][list-org-repos] APIs to build up a list of all the repositories the authenticated user has access to. If your app is doing this, you'll be able to get rid of all the organization-related API calls and just use the[List your repositories][list-your-repos] API.

If your app uses the[List your repositories][list-your-repos] API for another purpose, you'll need to update your app to handle the new organization-owned repositories we'll be returning.

The[List user organizations][list-user-organizations] API is intended provide[public organization memberships][public-org-membership] for any user. When you use this API to fetch*your own* organizations, this API currently returns your public and private organization memberships.

Soon, this API will only return public organization memberships.

If your app uses the[List user organizations][list-user-organizations] API to fetch all of the organization memberships (public and private) for the authenticated user, you'll need to update your app to use the[List your organizations][list-your-organizations] API instead. The[List your organizations][list-your-organizations] API returns all organizations (public and private) that your app is authorized to access.

OAuth requests will soon require minimum[scopes][] in order to access the[List your organizations][list-your-organizations] API.

Currently, the API response always includes your[public organization memberships][public-org-membership], regardless of the OAuth scopes associated with your request. If you have`user`,`read:org`,`write:org`, or`admin:org` scope, the response also includes your private organization memberships.

Soon, this API will only return organizations that your authorization allows you to operate on in some way (e.g., you can list teams with`read:org` scope, you can publicize your organization membership with`user` scope, etc.). Therefore, this API will require at least`user` or`read:org` scope. (`write:org` and`admin:org` scope implicitly include`read:org` scope.) OAuth requests with insufficient scope will receive a`403 Forbidden` response.

If you[authenticate via username and password][username-password-authn], you are not affected by this change.

If your app only needs to fetch the user's public organization memberships, you should use the[List user organizations][list-user-organizations] API instead. Since that API only returns public information, it does not require any scopes.

Starting**today**, these new APIs are available for developers to preview. We expect the preview period to last for four weeks. (Stay tuned to the developer blog for updates.) At the end of the preview period, these additions will become official components of the GitHub API.

While these additions are in their preview period, you'll need to provide the following custom media type in the`Accept` header:

During the preview 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.

At the end of the preview period, we will announce the start of a migration period. At that time, developers should update their applications to use the new APIs for managing organization admins. During this period, you will still be able to use the Owners team to manage your organization's admins, so that you have time to update your applications to use the new APIs without breakage. We expect the migration period to last for four weeks.

At the end of the migration period, the Owners team will no longer be special, and you'll no longer be able to rely on it for managing organization admins.

If you have any questions or feedback, please[get in touch with us][contact]!

[contact]:https://github.com/contact?form[subject]=Organization+Admin+Pre-release+Preview

[list-your-repos]:/v3/repos/#list-your-repositories

[list-your-orgs]:/v3/orgs/#list-your-organizations

[list-org-repos]:/v3/repos/#list-organization-repositories

[add-org-membership]:/v3/orgs/members/#add-or-update-organization-membership

[list-org-members]:/v3/orgs/members/#members-list

[get-org-membership]:/v3/orgs/members/#get-organization-membership

[list-user-organizations]:/v3/orgs/#list-user-organizations

[list-your-organizations]:/v3/orgs/#list-your-organizations

[public-org-membership]:https://help.github.com/articles/publicizing-or-concealing-organization-membership

[username-password-authn]:/v3/auth/#via-username-and-password

[scopes]:/v3/oauth/#scopes

kind:change

title:Removing token attribute from Authorizations API responses

created_at:2014-12-08

author_name:ptoomey3

Since OAuth access tokens function like passwords, they should be treated with

care. Today we are making it easier to more securely work with authorizations

via the Authorizations API. We are deprecating the use use of the`token`

attribute in the majority of the[Authorizations API](/v3/oauth_authorizations/)

responses. For the[affected APIs][authorizations-token-deprecation-notice], the

`token` attribute will soon return an empty string. To get ready for that

change, we are giving developers a chance to

[preview the updated API](#preview-period) starting today.

The current[OAuth Authorizations API](/v3/oauth_authorizations/) requires GitHub to store the full value for

each OAuth token on our servers. In order to increase the security for our

users, we are changing our architecture to store the SHA-256 digest of OAuth

tokens instead. GitHub securely hashes user passwords using bcrypt and we want

to provide comparable security for OAuth tokens as well.

Rest assured that this change is an entirely proactive measure from GitHub and is not associated with any security incident.

This change affects any code that relies on accessing the`token` attribute from

[these OAuth Authorizations API responses][authorizations-token-deprecation-notice].

For example, our own[GitHub for Mac][github-for-mac] and

[GitHub for Windows][github-for-windows] applications relied on reading the`token`

from the[Get-or-create an authorization for a specific app][get-or-create-for-app] API, in order to support multiple installations of our desktop application for a single user.

In order to reduce the impact of removing the`token` attribute, the OAuth

Authorizations API has added a new request attribute (`fingerprint`), added

three new response attributes (`token_last_eight`,`hashed_token`, and

`fingerprint`), and added[one new API][get-or-create-for-app-fingerprint].

While these new APIs and attributes do not replace the full functionality that

previously existed, they can be used in place of`token` for most common use cases.

*`token_last_eight` returns the last eight characters of the associated OAuth

token. As an example,`token_last_eight` could be used to display a list of

partial token values to help a user manage their OAuth tokens.

*`hashed_token` is the base64 of the SHA-256 digest of the token.

`hashed_token` could be used to programmatically validate that a given token

matches an authorization returned by the API.

*`fingerprint` is a new optional request parameter that allows an OAuth

application to create multiple authorizations for a single user.`fingerprint`

should be a string that distinguishes the new authorization from others

for the same client ID and user.

For example, to differentiate installations of a desktop application across

multiple devices you might set`fingerprint` to

`SHA256_HEXDIGEST("GitHub for Mac - MAC_ADDRESS_OF_MACHINE")`. Since

`fingerprint` is not meant to be a user-facing value, you should still set

the`note` attribute to help a user differentiate between authorizations on their

[OAuth applications listing on GitHub][app-listing].

*[Get-or-create an authorization for a specific app and fingerprint][get-or-create-for-app-fingerprint]

is a new API that is analagous to the

[Get-or-create an authorization for a specific app][get-or-create-for-app]

API, but adds support for the new`fingerprint` request parameter.

We are making the new Authorizations 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.

While these new APIs are in their preview period, you’ll need to provide the

following custom media type in the Accept header:

We expect the preview period to last 4-6 weeks. (Stay tuned to the developer blog for updates.) At the end of the preview period, these changes will become an official and stable part of GitHub API.

At the end of the preview period, we will announce the start of a migration period. Developers will have 8 weeks to update existing code to use the new APIs.

Some users may be curious why we are not using bcrypt to hash our OAuth tokens

like we do for user passwords. Bcrypt is purposefully computationally expensive

in order to mitigate brute force attacks against low entropy passwords. However,

OAuth tokens are highly random and are not susceptible to brute force attacks.

Given that OAuth token validation occurs for each request to the API we chose

SHA-256 for performance reasons.

If you have any questions or feedback, please[drop us a line][contact].

[contact]:https://github.com/contact?form[subject]=Removing+authorizations+token

[app-listing]:https://github.com/settings/applications

[create-a-new-authorization]:/v3/oauth_authorizations/#create-a-new-authorization

[get-or-create-for-app]:/v3/oauth_authorizations/#get-or-create-an-authorization-for-a-specific-app

[get-or-create-for-app-fingerprint]:/v3/oauth_authorizations/#get-or-create-an-authorization-for-a-specific-app-and-fingerprint

[github-for-mac]:https://mac.github.com/

[github-for-windows]:https://windows.github.com/

[authorizations-token-deprecation-notice]:/v3/oauth_authorizations/#deprecation-notice

kind:change

title:New Attributes for Starring API

created_at:2014-12-09

author_name:arfon

You can now see when a user starred a repository. To receive the new response format containing the`starred_at` field, request the new media type:

Note the starred repository is now available in the repo field.

If you have any questions or feedback about these changes, please[drop us a line][contact].

[starring]:/v3/activity/starring/#list-repositories-being-starred-with-star-creation-timestamps

[contact]:https://github.com/contact?form[subject]=New+Attributes+for+Starring+API