You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: docs/api.md
+24-10Lines changed: 24 additions & 10 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,32 +1,35 @@
1
1
---
2
-
sidebar_position: 8
2
+
id: api
3
+
title: 🧪 Tramline API
4
+
sidebar_label: 🧪 Tramline API
5
+
sidebar_position: 7
3
6
---
4
7
5
-
# 🧪 Tramline API
8
+
Tramline currently exposes 3 API endpoints to fetch release information and to send custom build metadata. Before you start, you need your API credentials to make requests. To get these click on **Organization Settings** in the top navbar:
6
9
7
-
Tramline currently exposes three API endpoints to fetch release information and to send custom build metadata to Tramline.
10
+
8
11
9
-
You need your `Account ID` and `API Key` before you can make any requests. To get these click on **Settings** in the dropdown on the top-right:
12
+
Under the **Settings** tab, inside the **API** section, you will find the `Account ID` and the `API key` that will be used later for all API calls.
You can send custom metadata to be displayed on Tramline dashboard about your build. Each metadata should have a unique identifier, and its value can be numerical or textual. The trend of all numeric metadata will be shown on Tramline dashboard.
127
136
128
137
Examples of metadata: app launch time, unit test coverage etc.
@@ -197,6 +206,7 @@ The `external_metadata` in the request body should adhere to the following schem
197
206
```
198
207
199
208
Sample request body:
209
+
200
210
```json
201
211
{
202
212
"external_metadata": [
@@ -227,3 +237,7 @@ Sample request body:
227
237
]
228
238
}
229
239
```
240
+
241
+
#### Response
242
+
243
+
If the schema is valid and the request is successful, the response will be a `200 OK`.
Tramline automates away a lot of boilerplate work and opines on some sensible defaults. We will continue to add more automations and hopefully also add controls to chose which ones to run.
25
+
Tramline automates away a lot of boilerplate work and opines on some sensible defaults. We will continue to add more automations and hopefully also add controls to chose which ones to run. Currently, some sensible automations (that everyone should do) are just magically done for you, and some require enabling manually.
26
+
27
+
If you have suggestions for common processes that Tramline can automate for you, which don't exist in this list down below, [please let us know](mailto:[email protected])!
28
+
29
+
## Cut a release branch
30
+
31
+
:::tip
32
+
This automation is run when a [new release is prepared](/using-tramline/release-management/new-release).
33
+
:::
34
+
:::info
35
+
Release branches are only cut for specific branching strategies. See [Branching Strategies](using-tramline/release-management/branching-strategies).
36
+
:::
37
+
38
+
On starting a new release, we automatically cut a release branch from the configured working branch for the repo. The release branch takes the pattern of `r/name-of-release-train/date-of-release`. For example, if your release train is called **Nightly**, the release branch will be <ReleaseBranchname="nightly"n=''/>. Additional releases during the day will be <ReleaseBranchname="nightly"n='1'/>.
39
+
40
+
## Pre-release pull requests
41
+
42
+
:::tip
43
+
This automation is run when a [new release is prepared](/using-tramline/release-management/new-release).
44
+
:::
45
+
:::info
46
+
Only works for [Parallel Working and Release Branch](/using-tramline/release-management/branching-strategies#parallel-working-and-release-branch) strategy.
47
+
:::
48
+
49
+
```mermaid
50
+
gitGraph
51
+
branch release
52
+
commit id: "previously"
53
+
checkout main
54
+
commit id: "commit 1"
55
+
commit id: "commit 2"
56
+
checkout release
57
+
merge main tag: "Start of release 1.0.0"
58
+
checkout main
59
+
commit id: "commit 3"
60
+
commit id: "commit 4"
61
+
commit id: "commit 5"
62
+
checkout release
63
+
merge main tag: "Start of Release 1.1.0"
64
+
checkout main
65
+
commit id: "commit 6"
66
+
```
25
67
26
-
This is a list of important things Tramline currently automatically does with little to no user intervention.
68
+
The working branch (eg. `main`) is merged into the static release branch (eg. `release`) automatically at the the start of every release.
27
69
28
-
## Cutting a release branch
70
+
## Start release flow for new commits
29
71
30
-
On starting a new release, we automatically cut a release branch from the specified working branch for the repo.
72
+
:::tip
73
+
This automation is run when [new commits land on the release branch](/using-tramline/working-pane/stability).
74
+
:::
31
75
32
-
This is always in the form of `r/name-of-release-train/date-of-release`.
76
+
When you land fixes to your release branch for an active release, the Tramline release flow automatically kicks off again. If you have Internal Releases enabled, on the arrival of every new commit, a new internal release process will start. If you only have Release Candidates enabled, only the release candidate process will automatically start. When any of this happens, the previous internal or RC builds are marked as stale, so that you can start working on the fresh builds.
33
77
34
-
For example, if your release train is called **Nightly**, the release branch will be <ReleaseBranchname="nightly"n=''/>. Additional releases during the day will be <ReleaseBranchname="nightly"n='1'/>.
78
+
## Trigger workflows
35
79
36
-
The release will listen to commits on this branch after it has been created.
80
+
:::tip
81
+
This automation is run when [new commits land on the release branch](/using-tramline/working-pane/stability).
82
+
:::
37
83
38
-
## Cutting a release tag at the end of a release
84
+
When an internal or release candidate process starts, the associated workflow is automatically triggered. The subsequent updates to that workflow are also tracked and updated in the dashboard.
39
85
40
-
Once the release is finalized, we automatically tag the last commit that was released with the version generated by the release train. If the released version is `1.0.0`. The tag will be `v1.0.0`.
86
+
## Trigger distributions
41
87
42
-
If you're using the GitHub integration for source control, we will also create a [GitHub release](https://docs.github.com/en/repositories/releasing-projects-on-github/managing-releases-in-a-repository) with an auto-generated changelog.
88
+
:::info
89
+
Enable this in your [submission settings](/using-tramline/release-management/release-settings#submission-settings).
90
+
:::
43
91
44
-
## Creating and merging pull requests
92
+
When a workflow finishes and a build is found, Tramline can optionally auto-submit the build to the configured distribution channel.
45
93
46
-
We wholly manage pull requests around release branches while starting and ending a release (depending on the branching strategy selected).
94
+
## Cancel previous workflow run
47
95
48
-
See [Branching Strategies](/branching-strategies)for more information.
96
+
When a new commit lands, and if there's already a workflow running for a previous commit, Tramline will attempt to cancel the previous workflow run. We do this to avoid wasting compute minutes.
49
97
50
-
## Managing version names and build numbers
98
+
## Apply change queue
51
99
52
-
### Build number
100
+
:::info
101
+
Enable build queues in your [release train settings](/using-tramline/release-management/release-settings#advanced-settings).
102
+
:::
53
103
54
-
Every app that is added to Tramline maintains an atomic counter for the build number. Regardless of what trains are running for the app, every workflow run will internally and externally update the build number for the generated build.
104
+
Changes that land on the release branch can optionally be staged in a [Change Queue](/using-tramline/build-processing/build-queue). The change queue gets automatically drained if either the number of changes in the queue exceed the configured limit or if the configured batch-time has passed.
55
105
56
-
This ensures that every build generated by Tramline across configured workflows always have a unique value.
106
+
## Track ongoing work
57
107
58
-
### Version Name
108
+
:::tip
109
+
This automation is always available as long as the release is active. See [changeset tracking](/using-tramline/working-pane/changeset-tracking).
110
+
:::
59
111
60
-
Version names are processed in a `major.minor.patch` format, where the `patch` term is optional.
112
+
All the pull requests that directly target the release branch (eg. `r/production/2022-12-31-1`) are automatically tracked and updated in the [changeset tracking](/using-tramline/working-pane/changeset-tracking) dashboard.
61
113
62
-
✅ Allowed versions:
63
-
```
64
-
1.2.0
65
-
4.2.1
66
-
16.9
67
-
```
114
+
68
115
69
-
❌ Invalid versions:
70
-
```
71
-
1
72
-
1.2.3.4
73
-
```
116
+
## Bumping versions and build numbers
74
117
75
-
Every new release increments the `minor` version.
118
+
### Versions
76
119
77
-
Once your release has reached a store (App Store or Play Store) production channel and has been distributed to at least some percentage of users (via staged rollout), any new commit on the release branch increments the `patch` version. When that happens, your release enters a `hotfix` mode.
120
+
Versions are automatically managed by Tramline. New releases start with a minor or major version bump (in SemVer terminology). When fixes land in the middle of a production rollout, the patch version always gets auto-bumped for the new changes.
78
121
79
-
### Hotfix
122
+
Similarly, when starting new hotfix releases, the patch version always get auto-bumped.
80
123
81
-
A release in `hotfix` mode simply means that you are pushing changes on the build that has reached some of your user-base and has a bug that warrants immediate fix rather than a new release altogether.
124
+
### Build numbers
82
125
83
-
### New release
126
+
Every build created generated through Tramline always has a unique build number. This is true across workflows, and across trains. Tramline maintains an atomic counter internally and automatically updates the build number through the [workflow triggering](/using-tramline/working-pane/stability) mechanism.
84
127
85
-
```
86
-
1.0.0 --> 1.1.0
87
-
```
128
+
## Merging fixes back
88
129
89
-
### New commits after production distribution has begun
130
+
:::tip
131
+
This is applicable for all [branching strategies](/using-tramline/release-management/branching-strategies).
132
+
:::
133
+
:::tip
134
+
Tramline will always automatically try to merge (not just create) all PRs that are created by Tramline, whenever possible (depending on required checks etc.).
135
+
:::
90
136
91
-
```
92
-
1.1.0 --> 1.1.1
93
-
```
94
137
95
-
## Triggering step workflows on commits
96
138
97
-
When you start a release or when you land commits on a release branch; we automatically run the steps and their workflows and send the builds generated from the workflows to the correct build channels.
139
+
Tramline can automatically backmerge changes from the release branch to your working branch and any upcoming release branches. There are two backmerge strategy options available.
140
+
141
+
### Continuously as changes land
142
+
143
+
Any PRs or commits merged into the release branch will be "backmerged" into the working branch. As new changes land, this process repeats so that the working branch is always up to date with the release branch. This is helpful for teams that do a number of fixes directly on the release branch so that the code is merged back to the "trunk" as _quickly_ as possible.
144
+
145
+
:::info
146
+
Depending on the [VCS integration](/integrations/version-control), the way cherry-picks happen have will slight variations.
147
+
:::
148
+
149
+
These running PRs created by Tramline are sometimes referred to as _Patch PRs_. These PRs get also get assigned to the original authors of the relevant change/commit.
150
+
151
+
### End of release
152
+
153
+
:::info
154
+
A backmerge branch will only be created if commits are found on the release branch that are not on the working branch.
155
+
:::
156
+
157
+
At the end of the release cycle, Tramline will create a backmerge branch and open a pull request to merge the release branch back into the working branch and also to any upcoming release branch.
158
+
159
+
## Notifications
160
+
161
+
:::info
162
+
Enable [Notifications](/using-tramline/quality-and-monitoring/notifications) in your [release train settings](/using-tramline/release-management/release-settings).
163
+
:::
164
+
165
+
### Attach builds
166
+
167
+
Along with all the available notifications, the "build available" notification specifically attaches the Internal or Release Candidate build as a part of the Slack notification. This is helpful for QAs or other folks in the configured Slack channel to quickly download the build for testing.
168
+
169
+
### Tester notes
170
+
171
+
When a new build is available to download from Tramline, in addition to the build itself, Tramline also sends the list of changes that were made for the build (since the last build) in the Slack notification. This tells anyone who is downloading the build what changes were made in it. The same information is also available in the Tramline dashboard.
172
+
173
+
## Create VCS tags
174
+
175
+
:::info
176
+
Enable tagging in your [release train settings](/using-tramline/release-management/release-settings).
177
+
:::
178
+
179
+
Tramline cuts git tags on your version control in a couple of different scenarios:
180
+
181
+
### End of a release
182
+
183
+
When the release ends, we automatically tag the last commit that was released at the end. If the released version is `1.0.0`. The tag will be `v1.0.0`.
184
+
185
+
### When a production submission finishes
186
+
187
+
For cases where you anticipate sending more than one build to the store, we also allow tagging each submission that actually went to the store. So in a single release, if you first partially release 1.0.0 to the production track on Play Store, and then land a patch fix and release 1.0.1 to 100%, you will get two tags: `v1.0.0` and `v1.0.1` against the appropriate commits.
188
+
189
+
## Create VCS release
190
+
191
+
:::tip
192
+
VCS releases are created at the [end of a release](#end-of-a-release).
193
+
:::
194
+
195
+
If you're using the [GitHub integration](/integrations/version-control/github) for version control, Tramline will automatically create a [GitHub release](https://docs.github.com/en/repositories/releasing-projects-on-github/managing-releases-in-a-repository) with an auto-generated changelog.
196
+
197
+
## Pick the correct version for hotfixes
198
+
199
+
When you start a [hotfix release](/using-tramline/special-cases/hotfix), Tramline will automatically pick the correct version to be hotfix'd (the last completed release). When the hotfix release starts, and if there's a diff — between the current hotfix changes and the last release — the release will jump straight into to creating a new Release Candidate build and will skip Internal builds to save time.
200
+
201
+
## Start releases on a schedule
202
+
203
+
:::info
204
+
Add a schedule to your release in the [release train settings](/using-tramline/release-management/release-settings).
205
+
:::
206
+
207
+
[Scheduled releases](/using-tramline/release-management/scheduled-release) automatically start a new release on the specified date and retain the schedule for subsequent releases. You can also optionally set a scheduled release to automatically stop on failure.
208
+
209
+
Additionally, if your release spans across a future release, the future release gets automatically adjusted.
210
+
211
+
212
+
213
+
## Update Export Compliance Information in App Store Connect
214
+
215
+
If enabled, Tramline will automatically sets the `usesNonExemptEncryption` to be `false` for all builds as they get upload to the App Store.
216
+
217
+
## Upload builds to Tramline
218
+
219
+
By default, all builds generated by your CI workflows as artifacts are automatically uploaded to Tramline. This is true for the following file types: `aab`, `apk` and `ipa`. They are subsequently also available for download from the [Tramline dashboard](/using-tramline/working-pane/stability) and [Slack notifications](/using-tramline/working-pane/stability#notifications).
220
+
221
+
## Default release notes from last release
222
+
223
+
Tramline will automatically apply "What's new" text or release notes from your previous release version to populate the release notes for the current release.
224
+
225
+
Additionally, if you manually add new locales for your release notes directly on the stores, Tramline will automatically pull them up in the next release.
226
+
227
+
## Pull Requests
228
+
229
+
:::tip
230
+
Pull requests are created under a variety of circumstances ([see above](/automations)).
231
+
:::
98
232
99
-
This ensures that all the users and stakeholders of all the relevant build channels are kept up-to-date on new changes without requiring manually sharing builds around. This is especially handy when the app is being QA'd (internally or externally) via the review steps.
233
+
There are a few default automatic settings for all pull requests created by Tramline:
100
234
101
-
<!--TODO##Storingbuilds-->
102
-
<!--TODO##PatchingupmetadataonAppStore-->
235
+
* If the PR is on the [GitHub VCS integration](/integrations/version-control/github), Tramline will try to set the [auto-merge](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/incorporating-changes-from-a-pull-request/automatically-merging-a-pull-request) option (if possible).
236
+
* Even if auto-merge flag is not possible (eg. other VCS integrations), Tramline will continually try to auto-merge until all the checks pass.
237
+
* For [cherry-pick PRs](#continuously-cherry-pick-commits) (or "patch" PRs), Tramline will reference-tag the name of the author of the cherry-pick commit in the body of the PR.
0 commit comments