Skip to content

Commit 6a78479

Browse files
author
Hubot
committed
Sync changes from upstream repository
1 parent cbf17ee commit 6a78479

File tree

9 files changed

+332
-3
lines changed

9 files changed

+332
-3
lines changed

‎content/changes/2016-02-19-source-import-preview-api.md‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
---
2+
kind: change
3+
title: GitHub Importer Preview API
4+
created_at: 2016-02-19
5+
author_name: spraints
6+
---
7+
8+
We've added an API for source imports, which will let you start an import from a Git, Subversion, Mercurial, or Team Foundation Server source repository. This is the same functionality as [the GitHub Importer](https://import.github.com/).
9+
10+
To access [the Source Import API][docs] during the preview period, you must provide a custom [media type][media-type] in the `Accept` header:
11+
12+
application/vnd.github.barred-rock-preview
13+
14+
If you have any questions or feedback, please [let us know][contact]!
15+
16+
[media-type]: /v3/media
17+
[docs]: /v3/migration/source_imports/
18+
[contact]: https://github.com/contact?form%5Bsubject%5D=Source+Import+API

‎content/v3/meta.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -30,3 +30,4 @@ Name | Type | Description
3030
`hooks`|`array` of `strings` | An Array of IP addresses in CIDR format specifying the addresses that incoming service hooks will originate from on GitHub.com. Subscribe to the [API Changes blog](https://developer.github.com/changes/) or follow [@GitHubAPI](https://twitter.com/GitHubAPI) on Twitter to get updated when this list changes.
3131
`git`|`array` of `strings` | An Array of IP addresses in CIDR format specifying the Git servers for GitHub.com.
3232
`pages`|`array` of `strings` | An Array of IP addresses in CIDR format specifying the A records for [GitHub Pages](https://pages.github.com/).
33+
`importer`|`array` of `strings` | An Array of IP addresses specifying the addresses that source imports will originate from on GitHub.com.

‎content/v3/migration.md‎

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
---
2+
title: Migration
3+
---
4+
5+
# Migration
6+
7+
These APIs help you move projects to or from {{ site.data.variables.product.product_name }}.
8+
9+
{% if page.version == 'dotcom' %}
10+
11+
## [Enterprise Migrations][migrations]
12+
13+
The [Enterprise Migrations API][migrations] lets you move a repository from GitHub to GitHub Enterprise.
14+
15+
## [Source Imports][source_imports]
16+
17+
The [Source Imports API][source_imports] lets you import a source repository to
18+
{{ site.data.variables.product.product_name }}.
19+
20+
{% else %}
21+
22+
The migration APIs are only available on github.com. To learn more about migration,
23+
read the [API documentation on github.com](https://developer.github.com/v3/migration/)
24+
or check out the [Enterprise Migration Guide](https://help.github.com/enterprise/admin/guides/migrations/).
25+
26+
{% endif %}
27+
28+
[migrations]: /v3/migration/migrations/
29+
[source_imports]: /v3/migration/source_imports/

content/v3/orgs/migrations.md renamed to content/v3/migration/migrations.md

File renamed without changes.

‎content/v3/migration/source_imports.md‎

Lines changed: 206 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,206 @@
1+
---
2+
title: Source Imports | GitHub API
3+
---
4+
5+
# Source Imports
6+
7+
{:toc}
8+
9+
{% if page.version != 'dotcom' %}
10+
11+
{{#warning}}
12+
13+
This API is not currently available on GitHub Enterprise.
14+
15+
{{/warning}}
16+
17+
{% endif %}
18+
19+
{{#tip}}
20+
21+
The source import APIs are currently in public preview. During this period, the APIs may change in a backwards-incompatible way. To access the API during the preview period, you must provide a custom [media type](/v3/media) in the `Accept` header:
22+
23+
application/vnd.github.barred-rock-preview
24+
25+
{{/tip}}
26+
27+
The Source Import API lets you start an import from a Git, Subversion, Mercurial, or Team Foundation Server source repository. This is the same functionality as [the GitHub Importer](https://import.github.com/).
28+
29+
A typical source import would [start the import](#start-an-import) and then (optionally) [update the authors](#map-a-commit-author). A more detailed example can be seen in this diagram:
30+
31+
```
32+
+---------+ +--------+ +---------------------+
33+
| Tooling | | GitHub | | Original Repository |
34+
+---------+ +--------+ +---------------------+
35+
| | |
36+
| Start import | |
37+
|----------------------------->| |
38+
| | |
39+
| | Download source data |
40+
| |--------------------------------------------->|
41+
| | Begin streaming data |
42+
| |<---------------------------------------------|
43+
| | |
44+
| Get import progress | |
45+
|----------------------------->| |
46+
| "status": "importing" | |
47+
|<-----------------------------| |
48+
| | |
49+
| Get commit authors | |
50+
|----------------------------->| |
51+
| | |
52+
| Map a commit author | |
53+
|----------------------------->| |
54+
| | |
55+
| | |
56+
| | Finish streaming data |
57+
| |<---------------------------------------------|
58+
| | |
59+
| | Rewrite commits with mapped authors |
60+
| |------+ |
61+
| | | |
62+
| |<-----+ |
63+
| | |
64+
| | Update repository on GitHub |
65+
| |------+ |
66+
| | | |
67+
| |<-----+ |
68+
| | |
69+
| Map a commit author | |
70+
|----------------------------->| |
71+
| | Rewrite commits with mapped authors |
72+
| |------+ |
73+
| | | |
74+
| |<-----+ |
75+
| | |
76+
| | Update repository on GitHub |
77+
| |------+ |
78+
| | | |
79+
| |<-----+ |
80+
| | |
81+
| Get import progress | |
82+
|----------------------------->| |
83+
| "status": "complete" | |
84+
|<-----------------------------| |
85+
| | |
86+
| | |
87+
```
88+
89+
## Start an import
90+
91+
Start a source import to a GitHub repository using GitHub Importer.
92+
93+
PUT /repos/:owner/:repo/import
94+
95+
### Parameters
96+
97+
Name | Type | Description
98+
-----|------|--------------
99+
`vcs`|`string`|**Required** The originating VCS type. Can be one of "subversion", "git", "mercurial", or "tfvc".
100+
`vcs_url`|`url`|**Required** The URL of the originating repository.
101+
`vcs_username`|`string`|If authentication is required, the username to provide to `vcs_url`.
102+
`vcs_password`|`string`|If authentication is required, the password to provide to `vcs_url`.
103+
`tfvc_project`|`string`|For a tfvc import, the name of the project that is being imported.
104+
105+
#### Example
106+
107+
<%= json \
108+
:vcs => "subversion",
109+
:vcs_url => "http://svn.mycompany.com/svn/myproject",
110+
:vcs_username => "octocat",
111+
:vcs_password => "secret"
112+
%>
113+
114+
### Response
115+
116+
<%= headers 201, :Location => "https://api.github.com/repos/spraints/socm/import" %>
117+
<%= json :source_import %>
118+
119+
## Get import progress
120+
121+
View the progress of an import.
122+
123+
GET /repos/:owner/:repo/import
124+
125+
### Response
126+
127+
<%= headers 200 %>
128+
<%= json :source_import_complete %>
129+
130+
### Import `status`
131+
132+
This section includes details about the possible values of the `status` field of the Import Progress response.
133+
134+
An import that does not have errors will progress through these steps:
135+
136+
* `importing` - the "raw" step of the import is in progress. This is where commit data is fetched from the original repository. The import progress response will include `commit_count` (the total number of raw commits that will be imported) and `percent` (0 - 100, the current progress through the import).
137+
* `mapping` - the "rewrite" step of the import is in progress. This is where SVN branches are converted to Git branches, and where author updates are applied. The import progress response does not include progress information.
138+
* `pushing` - the "push" step of the import is in progress. This is where the importer updates the repository on GitHub. The import progress response will include `push_percent`, which is the percent value reported by `git push` when it is "Writing objects".
139+
* `complete` - the import is complete, and the repository is ready on GitHub.
140+
141+
If there are problems, you will see one of these in the `status` field:
142+
143+
* `auth_failed` - the import requires authentication in order to connect to the original repository. Make another "Start Import" request, and include `vcs_username` and `vcs_password`.
144+
* `error` - the import encountered an error. The import progress response will include the `failed_step` and an error message. [Contact support](https://github.com/contact?form%5Bsubject%5D=Source+Import+API+error) for more information.
145+
146+
If you query import status for an import started via the web UI, you may also see these states:
147+
148+
* `detecting` - you've entered a URL via the web UI, and the importer is figuring out what type of source control is present at the URL.
149+
* `detection_needs_auth` - you've entered a URL via the web UI, and the importer needs you to enter authentication credentials in the web UI in order to continue detection.
150+
* `detection_found_nothing` - the importer didn't recognize any source control at the URL entered via the web UI.
151+
* `detection_found_multiple` - the importer found several projects or repositories at the provided URL.
152+
* `waiting_to_push` - the raw and rewrite steps are complete, but a destination GitHub repository hasn't been created yet.
153+
154+
## Get commit authors
155+
156+
Each type of source control system represents authors in a different way. For example, a Git commit author has a display name and an email address, but a Subversion commit author just has a username. The GitHub Importer will make the author information valid, but the author might not be correct. For example, it will change the bare Subversion username `hubot` into something like `hubot <hubot@12341234-abab-fefe-8787-fedcba987654>`.
157+
158+
This API method and the "Map a commit author" method allow you to provide correct Git author information.
159+
160+
GET /repos/:owner/:repo/import/authors
161+
162+
### Parameters
163+
164+
Name | Type | Description
165+
-----|------|------------
166+
`since`|`string`|Only authors found after this id are returned. Provide the highest author ID you've seen so far. New authors may be added to the list at any point while the importer is performing the `raw` step.
167+
168+
### Response
169+
170+
<%= headers 200 %>
171+
<%= json :source_import_authors %>
172+
173+
## Map a commit author
174+
175+
Update an author's identity for the import. Your application can continue updating authors any time before you push new commits to the repository.
176+
177+
PATCH /repos/:owner/:repo/import/authors/:author_id
178+
179+
### Parameters
180+
181+
Name | Type | Description
182+
-----|------|--------------
183+
`email`|`string`|The new Git author email.
184+
`name`|`string`|The new Git author name.
185+
186+
### Example
187+
188+
<%= json \
189+
:email => "hubot@github.com",
190+
:name => "Hubot the Robot"
191+
%>
192+
193+
### Response
194+
195+
<%= headers 200 %>
196+
<%= json :source_import_author %>
197+
198+
## Cancel an import
199+
200+
Stop an import for a repository.
201+
202+
DELETE /repos/:owner/:repo/import
203+
204+
### Response
205+
206+
<%= headers 204 %>

‎layouts/sidebar.html‎

Lines changed: 9 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -49,6 +49,15 @@ <h3><a href="#" class="js-expand-btn collapsed arrow-btn" data-proofer-ignore></
4949
<li><a href="/v3/issues/milestones/">Milestones</a></li>
5050
</ul>
5151
</li>
52+
<% if @item[:version] == 'dotcom' %>
53+
<li class="js-topic">
54+
<h3><a href="#" class="js-expand-btn collapsed arrow-btn" data-proofer-ignore></a><a href="/v3/migration/">Migration</a></h3>
55+
<ul class="js-guides">
56+
<li><a href="/v3/migration/migrations/">Migrations</a></li>
57+
<li><a href="/v3/migration/source_imports/">Source Imports</a></li>
58+
</ul>
59+
</li>
60+
<% end %>
5261
<li class="js-topic">
5362
<h3><a href="#" class="js-expand-btn collapsed arrow-btn" data-proofer-ignore></a><a href="/v3/misc/">Miscellaneous</a></h3>
5463
<ul class="js-guides">
@@ -64,9 +73,6 @@ <h3><a href="#" class="js-expand-btn collapsed arrow-btn" data-proofer-ignore></
6473
<h3><a href="#" class="js-expand-btn collapsed arrow-btn" data-proofer-ignore></a><a href="/v3/orgs/">Organizations</a></h3>
6574
<ul class="js-guides">
6675
<li><a href="/v3/orgs/members/">Members</a></li>
67-
<% if @item[:version] == 'dotcom' %>
68-
<li><a href="/v3/orgs/migrations/">Migrations</a></li>
69-
<% end %>
7076
<li><a href="/v3/orgs/teams/">Teams</a></li>
7177
<li><a href="/v3/orgs/hooks/">Webhooks</a></li>
7278
</ul>

‎lib/responses/meta.rb‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -9,6 +9,10 @@ module Responses
99
:pages => [
1010
"192.30.252.153/32",
1111
"192.30.252.154/32"
12+
],
13+
:importer => [
14+
"54.158.161.132",
15+
"54.226.70.38"
1216
]
1317
}
1418

‎lib/responses/source_imports.rb‎

Lines changed: 64 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,64 @@
1+
2+
module GitHub
3+
module Resources
4+
module Responses
5+
SOURCE_IMPORT ||= {
6+
"vcs" => "subversion",
7+
"vcs_url" => "http://svn.mycompany.com/svn/myproject",
8+
"status" => "importing",
9+
"status_text" => "Importing...",
10+
"authors_count" => 0,
11+
"percent" => 42,
12+
"commit_count" => 1042,
13+
"url" => "https://api.github.com/repos/octocat/socm/import",
14+
"html_url" => "https://import.github.com/octocat/socm/import",
15+
"authors_url" => "https://api.github.com/repos/octocat/socm/import/authors",
16+
"repository_url" => "https://api.github.com/repos/octocat/socm"
17+
}
18+
19+
SOURCE_IMPORT_COMPLETE ||= {
20+
"vcs" => "subversion",
21+
"vcs_url" => "http://svn.mycompany.com/svn/myproject",
22+
"status" => "complete",
23+
"status_text" => "Done",
24+
"authors_count" => 4,
25+
"url" => "https://api.github.com/repos/octocat/socm/import",
26+
"html_url" => "https://import.github.com/octocat/socm/import",
27+
"authors_url" => "https://api.github.com/repos/octocat/socm/import/authors",
28+
"repository_url" => "https://api.github.com/repos/octocat/socm"
29+
}
30+
31+
SOURCE_IMPORT_AUTHOR ||= {
32+
"id" => 2268557,
33+
"remote_id" => "nobody@fc7da526-431c-80fe-3c8c-c148ff18d7ef",
34+
"remote_name" => "nobody",
35+
"email" => "hubot@github.com",
36+
"name" => "Hubot",
37+
"url" => "https://api.github.com/repos/octocat/socm/import/authors/2268557",
38+
"import_url" => "https://api.github.com/repos/octocat/socm/import"
39+
}
40+
41+
SOURCE_IMPORT_AUTHORS ||= [
42+
SOURCE_IMPORT_AUTHOR,
43+
{
44+
"id" => 2268558,
45+
"remote_id" => "svner@fc7da526-431c-80fe-3c8c-c148ff18d7ef",
46+
"remote_name" => "svner",
47+
"email" => "svner@fc7da526-431c-80fe-3c8c-c148ff18d7ef",
48+
"name" => "svner",
49+
"url" => "https://api.github.com/repos/octocat/socm/import/authors/2268558",
50+
"import_url" => "https://api.github.com/repos/octocat/socm/import"
51+
},
52+
{
53+
"id" => 2268559,
54+
"remote_id" => "svner@example.com@fc7da526-431c-80fe-3c8c-c148ff18d7ef",
55+
"remote_name" => "svner@example.com",
56+
"email" => "svner@example.com@fc7da526-431c-80fe-3c8c-c148ff18d7ef",
57+
"name" => "svner@example.com",
58+
"url" => "https://api.github.com/repos/octocat/socm/import/authors/2268559",
59+
"import_url" => "https://api.github.com/repos/octocat/socm/import"
60+
}
61+
]
62+
end
63+
end
64+
end

‎nanoc.yaml‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -90,6 +90,7 @@ redirects:
9090
- /changes/2013-2-13-sortable-stars/: /changes/2013-02-14-sortable-stars/
9191
- /changes/2013-3-1-new-hookshot-coming/: /changes/2013-03-01-new-hookshot-coming/
9292
- /changes/2014-2-10-ping-event-for-webhooks/: /changes/2014-02-10-ping-event-for-webhooks/
93+
- /v3/orgs/migrations/: /v3/migration/migrations/
9394

9495

9596
# The syntax to use for patterns in the Rules file. Can be either `"glob"`

0 commit comments

Comments
 (0)