carlos / carloku Public

Download this file

1	# Channels
2
3	A channel is a pointer with a name. It says which shipped version an app
4	is serving, and promoting is the act of moving it. Nothing is rebuilt
5	between one channel and the next — the bytes that were tested are the
6	bytes that go live, which is the whole reason the platform separates
7	shipping from promoting.
8
9	## You start with one
10
11	Every app is created with a single channel called `edge`, and
12	`carlos deploy` lands there. That is enough for most apps: you deploy,
13	and it is live. To see where things stand:
14
15	```sh
16	carlos channels -app hello
17	```
18
19	Nothing is ever promoted *onto* the entry channel. Deploys land there, and
20	promotion moves a version from it to whatever comes next — so with one
21	channel there is no promotion step at all.
22
23	## Adding a stage in front of production
24
25	When you want a version to sit somewhere before a wider audience sees it,
26	declare a pipeline. The starter template adds a `production` channel
27	behind `edge`:
28
29	```sh
30	carlos pipeline init -app hello -template edge-production
31	```
32
33	That gives `production` a 24-hour bake window, a passkey requirement on
34	promotion, and an approval on any change to those rules — so the
35	protection cannot be quietly removed later either. The other template,
36	`full-ladder`, sets up `edge → beta → stable` with bakes of 24 and 72
37	hours and the passkey on `stable`.
38
39	Once a pipeline exists, deploys still land on `edge` and you move a
40	version forward by naming it:
41
42	```sh
43	carlos promote -app hello a1b2c3d production
44	```
45
46	A channel is entered from the one immediately before it and no other, so
47	"it ran on edge for a day first" is a fact about the bytes rather than a
48	claim about process. Promoting the same version twice succeeds and
49	changes nothing.
50
51	The rules a channel can carry — bake windows, passkeys, approval counts —
52	are all editable after the fact with
53	[carlos pipeline](https://carlosframework.com/docs/cli/#carlos-pipeline),
54	and [carlos promote](https://carlosframework.com/docs/cli/#carlos-promote)
55	documents the rest of its own flags.
56
57	## Putting a version back
58
59	Rollback points a channel at whatever it was serving before:
60
61	```sh
62	carlos rollback -app hello production
63	```
64
65	The outgoing version goes onto the channel's history as it leaves, so
66	running the same command again returns you to where you started — useful
67	when the rollback turns out to be the wrong call. A bake window does not
68	delay it: a box already has the version it is going back to, so there is
69	nothing to hold.
70
71	Two things are worth doing before you need this. Give your ships a
72	`-label` people can read, because that is what you will be squinting at
73	during a rollback. And get familiar with
74	[carlos releases](https://carlosframework.com/docs/cli/#carlos-releases)
75	while nothing is on fire: it answers "what is there to run", where
76	`carlos channels` answers "what is running".
77
78	## What reaching stable means
79
80	The `full-ladder` shape has a `stable` channel at the top, and a
81	promotion onto it can cut a semver tag: one name pointing at one release,
82	with the changelog of every iteration that led there compiled into it.
83
84	That happens when the version being promoted is an iteration of a target
85	rather than a commit sha, so set the target once:
86
87	```sh
88	carlos version target -app hello 0.5.0
89	```
90
91	From then on `carlos ship` with no `-version` mints the next iteration
92	under it. Promote a sha-named build to stable instead and the promotion
93	still lands. There is no tag to cut, and the promotion says so.
94
95	Tags are a naming convenience and an audit record, nothing more. No part
96	of getting your app running reads one, so an app that never uses them
97	loses nothing.
98
99	Full flags for the commands on this page:
100	[channels](https://carlosframework.com/docs/cli/#carlos-channels) and
101	[rollback](https://carlosframework.com/docs/cli/#carlos-rollback).
102