@recaptime-dev's working patches + fork for Phorge, a community fork of Phabricator. (Upstream dev and stable branches are at upstream/main and upstream/stable respectively.)
hq.recaptime.dev/wiki/Phorge
phorge
phabricator
Document API management of repositories and fix some issues with creating URIs via API
Summary:
Ref T10923. Primarily documents the process for creating repositories via the API.
Also fixes a couple of issues with `repositoryPHID` not being set yet when creating URIs via the API.
Test Plan:
- Followed all documented steps to create a new repository.
- Created and edited some new URIs from the web workflow, too.
Reviewers: chad
Reviewed By: chad
Maniphest Tasks: T10923
Differential Revision: https://secure.phabricator.com/D15870
+197
-1
+11
-1
src/applications/diffusion/editor/DiffusionURIEditor.php
+11
-1
src/applications/diffusion/editor/DiffusionURIEditor.php
···
3
3
final class DiffusionURIEditor
4
4
extends PhabricatorApplicationTransactionEditor {
5
5
6
+
private $repository;
7
+
private $repositoryPHID;
8
+
6
9
public function getEditorApplicationClass() {
7
10
return 'PhabricatorDiffusionApplication';
8
11
}
···
115
118
break;
116
119
case PhabricatorRepositoryURITransaction::TYPE_REPOSITORY:
117
120
$object->setRepositoryPHID($xaction->getNewValue());
121
+
$object->attachRepository($this->repository);
118
122
break;
119
123
case PhabricatorRepositoryURITransaction::TYPE_CREDENTIAL:
120
124
$object->setCredentialPHID($xaction->getNewValue());
···
151
155
152
156
switch ($type) {
153
157
case PhabricatorRepositoryURITransaction::TYPE_REPOSITORY:
158
+
// Save this, since we need it to validate TYPE_IO transactions.
159
+
$this->repositoryPHID = $object->getRepositoryPHID();
160
+
154
161
$missing = $this->validateIsEmptyTextField(
155
162
$object->getRepositoryPHID(),
156
163
$xactions);
···
208
215
$xaction);
209
216
continue;
210
217
}
218
+
219
+
$this->repository = $repository;
220
+
$this->repositoryPHID = $repository_phid;
211
221
}
212
222
break;
213
223
case PhabricatorRepositoryURITransaction::TYPE_CREDENTIAL:
···
315
325
if ($no_observers || $no_readwrite) {
316
326
$repository = id(new PhabricatorRepositoryQuery())
317
327
->setViewer(PhabricatorUser::getOmnipotentUser())
318
-
->withPHIDs(array($object->getRepositoryPHID()))
328
+
->withPHIDs(array($this->repositoryPHID))
319
329
->needURIs(true)
320
330
->executeOne();
321
331
$uris = $repository->getURIs();
+4
src/docs/user/userguide/diffusion.diviner
+4
src/docs/user/userguide/diffusion.diviner
···
53
53
details on the available options and guidance on managing and administrating
54
54
repositories, see @{article:Diffusion User Guilde: Managing Repositories}.
55
55
56
+
Repositories can also be managed via the API. For an overview on using the
57
+
API to create and edit repositories, see
58
+
@{article:Diffusion User Guide: Repositories API}.
59
+
56
60
57
61
Repository Clustering
58
62
=====================
+182
src/docs/user/userguide/diffusion_api.diviner
+182
src/docs/user/userguide/diffusion_api.diviner
···
1
+
@title Diffusion User Guide: Repositories API
2
+
@group userguide
3
+
4
+
Managing repositories with the API.
5
+
6
+
Overview
7
+
========
8
+
9
+
You can create and update Diffusion repositories using the Conduit API. This
10
+
may be useful if you have a large number of existing repositories you want
11
+
to import or apply bulk actions to.
12
+
13
+
For an introduction to Conduit, see @{article:Conduit API Overview}.
14
+
15
+
In general, you'll use these API methods:
16
+
17
+
- `diffusion.repository.edit`: Create and edit repositorie.
18
+
- `diffusion.uri.edit`: Create and edit repository URIs to configure
19
+
observation, mirroring, and cloning.
20
+
21
+
To create a repository, you'll generally do this:
22
+
23
+
- Call `diffusion.repository.edit` to create a new object and configure
24
+
basic information.
25
+
- Optionally, call `diffusion.uri.edit` to add URIs to observe or mirror.
26
+
- Call `diffusion.repository.edit` to activate the repository.
27
+
28
+
This workflow mirrors the workflow from the web UI. The remainder of this
29
+
document walks through this workflow in greater detail.
30
+
31
+
32
+
Create a Repository
33
+
===================
34
+
35
+
To create a repository, call `diffusion.repository.edit`, providing any
36
+
properties you want to set. For simplicity these examples will use the
37
+
builtin `arc call-conduit` client, but you can use whatever Conduit client
38
+
you prefer.
39
+
40
+
When creating a repository, you must provide a `vcs` transaction to choose
41
+
a repository type, one of: `git`, `hg` or `svn`.
42
+
43
+
You must also provide a `name`.
44
+
45
+
Other properties are optional. Review the Conduit method documentation from the
46
+
web UI for an exhaustive list.
47
+
48
+
```
49
+
$ echo '{
50
+
"transactions": [
51
+
{
52
+
"type": "vcs",
53
+
"value": "git"
54
+
},
55
+
{
56
+
"type": "name",
57
+
"value": "Poetry"
58
+
}
59
+
]
60
+
}' | arc call-conduit diffusion.repository.edit
61
+
```
62
+
63
+
If things work, you should get a result that looks something like this:
64
+
65
+
```lang=json
66
+
{
67
+
...
68
+
"response": {
69
+
"object": {
70
+
"id": 1,
71
+
"phid": "PHID-REPO-7vm42oayez2rxcmpwhuv"
72
+
},
73
+
...
74
+
}
75
+
...
76
+
}
77
+
```
78
+
79
+
If so, your new repository has been created. It hasn't been activated yet so
80
+
it will not show up in the default repository list, but you can find it in the
81
+
web UI by browsing to {nav Diffusion > All Repositories}.
82
+
83
+
Continue to the next step to configure URIs.
84
+
85
+
86
+
Configure URIs
87
+
==============
88
+
89
+
Now that the repository exists, you can add URIs to it. This is optional,
90
+
and if you're creating a //hosted// repository you may be able to skip this
91
+
step.
92
+
93
+
However, if you want Phabricator to observe an existing remote, you'll
94
+
configure it here by adding a URI in "Observe" mode. Use the PHID from the
95
+
previous step to identify the repository you want to add a URI to, and call
96
+
`diffusion.uri.edit` to create a new URI in Observe mode for the repository.
97
+
98
+
You need to provide a `repository` to add the URI to, and the `uri` itself.
99
+
100
+
To add the URI in Observe mode, provide an `io` transaction selecting
101
+
`observe` mode.
102
+
103
+
You may also want to provide a `credential`.
104
+
105
+
```
106
+
$ echo '{
107
+
"transactions": [
108
+
{
109
+
"type": "repository",
110
+
"value": "PHID-REPO-7vm42oayez2rxcmpwhuv"
111
+
},
112
+
{
113
+
"type": "uri",
114
+
"value": "https://github.com/epriestley/poems.git"
115
+
},
116
+
{
117
+
"type": "io",
118
+
"value": "observe"
119
+
}
120
+
]
121
+
}' | arc call-conduit diffusion.uri.edit
122
+
```
123
+
124
+
You should get a response that looks something like this:
125
+
126
+
```lang=json
127
+
{
128
+
...
129
+
"response": {
130
+
"object": {
131
+
"id": 1,
132
+
"phid": "PHID-RURI-zwtho5o7h3m6rjzgsgrh"
133
+
},
134
+
...
135
+
}
136
+
...
137
+
}
138
+
```
139
+
140
+
If so, your URI has been created. You can review it in the web UI, under
141
+
{nav Manage Repository > URIs}.
142
+
143
+
When satisfied, continue to the next step to activate the repository.
144
+
145
+
146
+
Activate the Repository
147
+
=======================
148
+
149
+
Now that any URIs have been configured, activate the repository with another
150
+
call to `diffusion.repository.edit`. This time, modify the existing repostitory
151
+
instead of creating a new one:
152
+
153
+
```
154
+
$ echo '{
155
+
"objectIdentifier": "PHID-REPO-7vm42oayez2rxcmpwhuv",
156
+
"transactions": [
157
+
{
158
+
"type": "status",
159
+
"value": "active"
160
+
}
161
+
]
162
+
}' | arc call-conduit diffusion.repository.edit
163
+
```
164
+
165
+
If that goes through cleanly, you should be all set. You can review the
166
+
repository from the web UI.
167
+
168
+
169
+
Editing Repositories
170
+
====================
171
+
172
+
To edit an existing repository, apply changes normally with
173
+
`diffusion.repository.edit`. For more details on using edit endpoints, see
174
+
@{article:Conduit API: Using Edit Endpoints}.
175
+
176
+
177
+
Next Steps
178
+
==========
179
+
180
+
Continue by:
181
+
182
+
- returning to the @{article:Diffusion User Guide}.