GitLabgitlab-org
cli
main
1// Package start implements `glab autoflow workflow start`.
2package start
4import (
5 "context"
6 "crypto/rand"
7 "encoding/base64"
8 "errors"
9 "fmt"
10 "io"
11 "os"
12 "strings"
14 "github.com/MakeNowJust/heredoc/v2"
15 "github.com/spf13/cobra"
16 autoflowrpcv1 "gitlab.com/gitlab-org/protos/gen/go/gitlab/autoflow/rpc/v1"
17 autoflowv1 "gitlab.com/gitlab-org/protos/gen/go/gitlab/autoflow/v1"
18 "google.golang.org/grpc/codes"
19 "google.golang.org/grpc/status"
21 "gitlab.com/gitlab-org/cli/internal/api"
22 "gitlab.com/gitlab-org/cli/internal/api/autoflow"
23 "gitlab.com/gitlab-org/cli/internal/cmdutils"
24 "gitlab.com/gitlab-org/cli/internal/commands/autoflow/autoflowutils"
25 "gitlab.com/gitlab-org/cli/internal/iostreams"
26 "gitlab.com/gitlab-org/cli/internal/mcpannotations"
27 "gitlab.com/gitlab-org/cli/internal/text"
28)
30type options struct {
31 io *iostreams.IOStreams
32 apiClient func(repoHost string) (*api.Client, error)
34 conn autoflowutils.Connection
35 script string
36 scriptFile string
37 idempotencyKey string
38 tokenBinding *cmdutils.SecretFile
39 kwargs []string
40 channels []string
41 outputFormat string
43 decodedTokenBinding []byte
44 parsedKwargs []*autoflowv1.Kwarg
45}
47// NewCmd returns the `glab autoflow workflow start` command.
48func NewCmd(f cmdutils.Factory) *cobra.Command {
49 opts := &options{
50 io: f.IO(),
51 apiClient: f.ApiClient,
52 }
54 cmd := &cobra.Command{
55 Use: "start",
56 Short: "Start an AutoFlow workflow. (EXPERIMENTAL)",
57 Long: heredoc.Docf(`
58 Submit a Starlark workflow definition to the AutoFlow service of GitLab Relay and start a workflow for it. The command returns once the workflow is persisted and does not wait for it to run.
60 The command exchanges your GitLab credential for a short-lived token for AutoFlow, so your user needs the %[1]stoken_exchange_autoflow_audience%[1]s feature flag on the GitLab instance. By default, the workflow belongs to the namespace of your organization.
62 %[1]s--kwarg%[1]s passes a keyword argument to the workflow's %[1]smain%[1]s function as JSON: %[1]snull%[1]s becomes %[1]sNone%[1]s, a number without a fraction or exponent an integer, an array a list and an object a dict. Sensitive values are not supported yet. %[1]s--channel%[1]s creates a channel and passes it as the keyword argument of the same name, so %[1]sglab autoflow workflow send%[1]s can send to it.
64 The output contains the workflow token, the token binding and a token for each channel. All of them are credentials:
66 - The workflow key and workflow token read or cancel the workflow later with %[1]sglab autoflow workflow get%[1]s and %[1]sglab autoflow workflow cancel%[1]s.
67 - The idempotency key and token binding re-submit the same workflow to get fresh tokens. Pass them with %[1]s--idempotency-key%[1]s and %[1]s--token-binding-file%[1]s, or the token binding in its environment variable. A re-submission returns the existing workflow and ignores the definition and the keyword arguments. A key without its binding gets %[1]sPermissionDenied%[1]s. It returns channel tokens for the channels it passes again.
68 `, "`") + text.ExperimentalString,
69 Example: heredoc.Doc(`
70 # Start the workflow in main.star on Runway staging
71 glab autoflow workflow start --hostname staging.gitlab.com \
72 --address staging.autoflow-gke.svc.gitlab.net:443 \
73 --script-file main.star
75 # Start a workflow with a keyword argument and a channel
76 glab autoflow workflow start --address relay.example.com:443 \
77 --script 'def main(w, count, inbox): return [gather(inbox) for _ in range(count)]' \
78 --kwarg count=2 --channel inbox
80 # Re-submit a workflow to get fresh tokens for it
81 glab autoflow workflow start --address relay.example.com:443 \
82 --idempotency-key glab-T3KQZ7WMXH4RJ2NVB6YLC5DPEA \
83 --token-binding-file token-binding.txt --script-file main.star
85 # Start an inline workflow and print the result as JSON
86 glab autoflow workflow start --address relay.example.com:443 \
87 --script 'def main(w): return "hello"' --output json
88 `),
89 Args: cobra.NoArgs,
90 ValidArgsFunction: cobra.NoFileCompletions,
91 // The output carries the workflow, channel and binding tokens.
92 Annotations: map[string]string{
93 mcpannotations.Exclude: "true",
94 },
95 RunE: func(cmd *cobra.Command, _ []string) error {
96 if err := opts.complete(); err != nil {
97 return err
98 }
99 if err := opts.validate(); err != nil {
100 return err
101 }
102 return opts.run(cmd.Context())
103 },
104 }
106 opts.conn.AddFlags(cmd)
107 fl := cmd.Flags()
108 fl.StringVar(&opts.script, "script", "", "Workflow definition as Starlark source.")
109 fl.StringVar(&opts.scriptFile, "script-file", "", "Path to a file with the workflow definition. Use - to read from standard input.")
110 fl.StringVar(&opts.idempotencyKey, "idempotency-key", "", "Key that deduplicates submissions within the namespace. Defaults to a random key. Without a token binding, the key starts a new workflow, and Relay refuses a key that an earlier workflow uses.")
111 fl.StringArrayVar(&opts.kwargs, "kwarg", nil, "Keyword argument of the workflow's main function, as <name>=<JSON value>. Sensitive values are not supported. Repeat for more arguments.")
112 fl.StringArrayVar(&opts.channels, "channel", nil, "Name of a channel to create and pass to the workflow's main function as the keyword argument of the same name. Repeat for more channels.")
113 opts.tokenBinding = autoflowutils.NewTokenBindingFlag(cmd)
114 cmdutils.EnableJSONOutput(cmd, opts.io, &opts.outputFormat)
116 cmd.MarkFlagsOneRequired("script", "script-file")
117 cmd.MarkFlagsMutuallyExclusive("script", "script-file")
118 cobra.CheckErr(cmd.MarkFlagFilename("script-file", "star"))
120 return cmd
121}
123func (o *options) complete() error {
124 if err := o.conn.Complete(); err != nil {
125 return err
126 }
128 if o.tokenBinding.FromStdin() && o.scriptFile == "-" {
129 return &cmdutils.FlagError{Err: errors.New("only one of --script-file and --token-binding-file can read from standard input")}
130 }
131 if o.tokenBinding.IsSet() {
132 // A binding without the key it was registered under cannot reach its
133 // workflow, so it would only be shared between new ones.
134 if o.idempotencyKey == "" {
135 return &cmdutils.FlagError{Err: errors.New("a token binding re-submits an earlier workflow, so it needs the --idempotency-key of that workflow")}
136 }
137 encoded, err := o.tokenBinding.Read(o.io.In)
138 if err != nil {
139 return err
140 }
141 o.decodedTokenBinding, err = base64.StdEncoding.DecodeString(encoded)
142 if err != nil {
143 return &cmdutils.FlagError{Err: fmt.Errorf("error parsing the token binding: %w", err)}
144 }
145 } else {
146 o.decodedTokenBinding = make([]byte, autoflow.TokenBindingSize)
147 if _, err := rand.Read(o.decodedTokenBinding); err != nil {
148 return fmt.Errorf("failed to generate token binding: %w", err)
149 }
150 }
152 if o.idempotencyKey == "" {
153 o.idempotencyKey = "glab-" + rand.Text()
154 }
156 return o.completeKwargs()
157}
159func (o *options) completeKwargs() error {
160 seen := map[string]struct{}{}
161 add := func(name string, value *autoflowv1.Value) error {
162 if name == "" {
163 return &cmdutils.FlagError{Err: errors.New("a keyword argument needs a name")}
164 }
165 if _, ok := seen[name]; ok {
166 return &cmdutils.FlagError{Err: fmt.Errorf("keyword argument %q is passed more than once", name)}
167 }
168 seen[name] = struct{}{}
169 o.parsedKwargs = append(o.parsedKwargs, &autoflowv1.Kwarg{Name: name, Value: value})
170 return nil
171 }
173 for _, kwarg := range o.kwargs {
174 name, raw, ok := strings.Cut(kwarg, "=")
175 if !ok {
176 return &cmdutils.FlagError{Err: fmt.Errorf("error parsing --kwarg %s: want <name>=<JSON value>", kwarg)}
177 }
178 value, err := autoflow.ParseValue([]byte(raw))
179 if err != nil {
180 return &cmdutils.FlagError{Err: fmt.Errorf("error parsing --kwarg %s: %w", name, err)}
181 }
182 if err := add(name, value); err != nil {
183 return err
184 }
185 }
186 for _, channel := range o.channels {
187 if err := add(channel, autoflow.ChannelValue(channel)); err != nil {
188 return err
189 }
190 }
191 return nil
192}
194func (o *options) validate() error {
195 if len(o.decodedTokenBinding) != autoflow.TokenBindingSize {
196 return &cmdutils.FlagError{Err: fmt.Errorf("error parsing the token binding: must decode to %d bytes, got %d", autoflow.TokenBindingSize, len(o.decodedTokenBinding))}
197 }
198 return nil
199}
201func (o *options) run(ctx context.Context) error {
202 definition, err := o.readDefinition()
203 if err != nil {
204 return err
205 }
206 client, conn, err := o.conn.Dial(ctx, o.io, o.apiClient)
207 if err != nil {
208 return err
209 }
210 defer conn.Close()
212 tokenBinding := base64.StdEncoding.EncodeToString(o.decodedTokenBinding)
213 ctx, cancel := context.WithTimeout(ctx, autoflowutils.CallTimeout)
214 defer cancel()
215 resp, err := client.StartWorkflow(ctx, &autoflowrpcv1.StartWorkflowRequest{
216 IdempotencyKey: o.idempotencyKey,
217 WorkflowDefinition: definition,
218 NamespaceId: o.conn.NamespaceID[:],
219 TokenBinding: o.decodedTokenBinding,
220 Kwargs: o.parsedKwargs,
221 })
222 if err != nil {
223 if !mayHavePersisted(err) {
224 return fmt.Errorf("failed to start workflow: %w", err)
225 }
226 return o.retryableError(tokenBinding, err)
227 }
229 return o.print(started{
230 WorkflowKey: resp.GetWorkflowKey(),
231 WorkflowToken: resp.GetWorkflowToken(),
232 NamespaceID: o.conn.NamespaceID.String(),
233 IdempotencyKey: o.idempotencyKey,
234 TokenBinding: tokenBinding,
235 ChannelTokens: channelTokens(resp.GetChannelTokens()),
236 })
237}
239// mayHavePersisted reports whether Relay may have stored the workflow before
240// the call failed with err. Only the same key and binding can reach it then.
241// With the other codes, Relay refused the request without storing a workflow
242// for it.
243func mayHavePersisted(err error) bool {
244 switch status.Code(err) {
245 case codes.Unavailable, codes.DeadlineExceeded, codes.Canceled, codes.Unknown, codes.Internal, codes.Aborted:
246 return true
247 default:
248 return false
249 }
250}
252func (o *options) retryableError(tokenBinding string, err error) error {
253 var binding string
254 switch file := o.tokenBinding.File(); {
255 case file != "" && file != "-":
256 binding = fmt.Sprintf("--token-binding-file %q", file)
257 case file == "" && o.tokenBinding.IsSet():
258 binding = "keep " + o.tokenBinding.Env() + " set"
259 default:
260 // A generated binding, or one read from standard input, exists only
261 // in this process.
262 saved, saveErr := saveTokenBinding(tokenBinding)
263 if saveErr != nil {
264 return fmt.Errorf("failed to start workflow, and failed to save the token binding to retry it: %w", errors.Join(err, saveErr))
265 }
266 binding = fmt.Sprintf("--token-binding-file %q", saved)
267 }
268 return fmt.Errorf("failed to start workflow (to retry without starting a second one, pass --idempotency-key %s and %s): %w", o.idempotencyKey, binding, err)
269}
271func saveTokenBinding(tokenBinding string) (string, error) {
272 f, err := os.CreateTemp("", "glab-autoflow-token-binding-")
273 if err != nil {
274 return "", err
275 }
276 _, err = f.WriteString(tokenBinding + "\n")
277 if err = errors.Join(err, f.Close()); err != nil {
278 return "", errors.Join(err, os.Remove(f.Name()))
279 }
280 return f.Name(), nil
281}
283func (o *options) readDefinition() ([]byte, error) {
284 definition, err := o.readDefinitionSource()
285 if err != nil {
286 return nil, err
287 }
288 if len(definition) == 0 {
289 return nil, fmt.Errorf("the workflow definition is empty")
290 }
291 return definition, nil
292}
294func (o *options) readDefinitionSource() ([]byte, error) {
295 switch o.scriptFile {
296 case "":
297 return []byte(o.script), nil
298 case "-":
299 b, err := io.ReadAll(o.io.In)
300 if err != nil {
301 return nil, fmt.Errorf("failed to read the workflow definition from standard input: %w", err)
302 }
303 return b, nil
304 default:
305 b, err := os.ReadFile(o.scriptFile)
306 if err != nil {
307 return nil, fmt.Errorf("failed to read the workflow definition: %w", err)
308 }
309 return b, nil
310 }
311}
313type started struct {
314 WorkflowKey string `json:"workflow_key"`
315 WorkflowToken string `json:"workflow_token"`
316 NamespaceID string `json:"namespace_id"`
317 IdempotencyKey string `json:"idempotency_key"`
318 TokenBinding string `json:"token_binding"`
319 ChannelTokens []channelToken `json:"channel_tokens,omitempty"`
320}
322type channelToken struct {
323 Channel string `json:"channel"`
324 Token string `json:"token"`
325}
327func channelTokens(tokens []*autoflowv1.ChannelToken) []channelToken {
328 out := make([]channelToken, 0, len(tokens))
329 for _, t := range tokens {
330 out = append(out, channelToken{Channel: t.GetChannelName(), Token: t.GetToken()})
331 }
332 return out
333}
335func (o *options) print(s started) error {
336 switch o.outputFormat {
337 case "json":
338 return o.io.PrintJSON(s)
339 default:
340 _, err := fmt.Fprintf(o.io.StdOut, //nolint:forbidigo // the credentials must reach the caller or the command fails
341 "workflow_key: %s\nworkflow_token: %s\nnamespace_id: %s\nidempotency_key: %s\ntoken_binding: %s\n",
342 s.WorkflowKey, s.WorkflowToken, s.NamespaceID, s.IdempotencyKey, s.TokenBinding)
343 if err != nil {
344 return err
345 }
346 for _, t := range s.ChannelTokens {
347 if _, err := fmt.Fprintf(o.io.StdOut, "channel_token.%s: %s\n", t.Channel, t.Token); err != nil { //nolint:forbidigo // the credentials must reach the caller or the command fails
348 return err
349 }
350 }
351 return nil
352 }
353}
Diagnostics9 git calls · 214 ms
CallStatusSizeTime0214 ms
discover200185 B3 ms
git.upload-pack discover http.response.status_code=200 git.upstream.cf_ray=- git.upstream.phase=fetch git.upstream.dur_ms=3 git.response.bytes=185 git.server.agent=git/2.56.g1891de4-Linux git.server.object_format=sha1 git.server.caps=agent ls-refs fetch server-option object-format git.server.fetch=shallow wait-for-done filter git.protocol.version=2 git.pkt.frames=9 git.pkt.data=7 git.pkt.flush=2 git.pkt.delim=0 git.pkt.bytes=185 git.pkt.payload.max=35
ls-refs20058 KiB · hit2 ms
git.upload-pack ls-refs http.response.status_code=200 git.upstream.cf_ray=- git.upstream.phase=ls-refs git.upstream.dur_ms=2 git.response.bytes=59849 git.response.cache=HIT git.response.duration_ms=2 git.protocol.version=2 git.pkt.frames=731 git.pkt.data=730 git.pkt.flush=1 git.pkt.delim=0 git.pkt.bytes=59849 git.pkt.payload.max=143 git.ls_refs.count=730 git.ls_refs.head=refs/heads/main
fetchcombine:blob:none+tree:2 · deepen 12004.2 KiB · hit3 ms
git.upload-pack fetch http.response.status_code=200 git.upstream.cf_ray=- git.upstream.phase=fetch git.upstream.dur_ms=3 git.response.bytes=4273 git.response.cache=HIT git.response.duration_ms=3 git.fetch.filter=combine:blob:none+tree:2 git.fetch.wants=0dd7574dce9e385c5c30540e6c15657adc6bdce9 git.fetch.haves.count=0 git.fetch.deepen=1 git.fetch.thin_pack=false git.fetch.ofs_delta=true git.protocol.version=2 git.pkt.frames=7 git.pkt.data=5 git.pkt.flush=1 git.pkt.delim=1 git.pkt.bytes=4273 git.pkt.payload.max=4173 git.sideband.band1.bytes=4173 git.sideband.band2.bytes=0 git.sideband.band3.bytes=0 git.pack.objects=11 git.pack.bytes=4173 git.fetch.wide.objects=11 git.fetch.wide.extra_bytes=3930 git.fetch.wide.blobs=0
fetchtree:0 · deepen 1020032 KiB · hit3 ms
git.upload-pack fetch http.response.status_code=200 git.upstream.cf_ray=- git.upstream.phase=fetch git.upstream.dur_ms=0 git.response.bytes=32926 git.response.cache=HIT git.response.duration_ms=3 git.fetch.filter=tree:0 git.fetch.wants=0dd7574dce9e385c5c30540e6c15657adc6bdce9 git.fetch.haves.count=0 git.fetch.deepen=10 git.fetch.thin_pack=false git.fetch.ofs_delta=true git.protocol.version=2 git.pkt.frames=22 git.pkt.data=20 git.pkt.flush=1 git.pkt.delim=1 git.pkt.bytes=32926 git.pkt.payload.max=32046 git.sideband.band1.bytes=32046 git.sideband.band2.bytes=0 git.sideband.band3.bytes=0 git.pack.objects=80 git.pack.bytes=32046 git.pack.ofs_delta=36 git.pack.ref_delta=0 git.pack.chain.max=2 git.pack.trailer=cb0bad5d7ffc514895d8b21c4dd470327f90bc91 git.pack.full=44Open pack map
fetchtree:02001.8 KiB · hit0 ms
git.upload-pack fetch http.response.status_code=200 git.upstream.cf_ray=- git.upstream.phase=fetch git.upstream.dur_ms=2 git.response.bytes=1857 git.response.cache=HIT git.response.duration_ms=0 git.fetch.filter=tree:0 git.fetch.wants=dce174ff8c632a19d17eea99c8a9b7c37fb2b592 git.fetch.haves.count=0 git.fetch.deepen=0 git.fetch.thin_pack=false git.fetch.ofs_delta=true git.protocol.version=2 git.pkt.frames=4 git.pkt.data=3 git.pkt.flush=1 git.pkt.delim=0 git.pkt.bytes=1857 git.pkt.payload.max=1830 git.sideband.band1.bytes=1830 git.sideband.band2.bytes=0 git.sideband.band3.bytes=0 git.pack.objects=1 git.pack.bytes=1830 git.pack.trailer=fb03183b7909876778f740d196d7516811003517Open pack map
fetchtree:0200173 B · hit2 ms
git.upload-pack fetch http.response.status_code=200 git.upstream.cf_ray=- git.upstream.phase=fetch git.upstream.dur_ms=3 git.response.bytes=173 git.response.cache=HIT git.response.duration_ms=2 git.fetch.filter=tree:0 git.fetch.wants=9842465ba0bef0fe35148002069a98d0492349fa git.fetch.haves.count=0 git.fetch.deepen=0 git.fetch.thin_pack=false git.fetch.ofs_delta=true git.protocol.version=2 git.pkt.frames=4 git.pkt.data=3 git.pkt.flush=1 git.pkt.delim=0 git.pkt.bytes=173 git.pkt.payload.max=146 git.sideband.band1.bytes=146 git.sideband.band2.bytes=0 git.sideband.band3.bytes=0 git.pack.objects=1 git.pack.bytes=146 git.pack.trailer=257bc2fe070f60e712099d7a0548db758c6c9692Open pack map
fetchtree:0200227 B · hit3 ms
git.upload-pack fetch http.response.status_code=200 git.upstream.cf_ray=- git.upstream.phase=fetch git.upstream.dur_ms=3 git.response.bytes=227 git.response.cache=HIT git.response.duration_ms=3 git.fetch.filter=tree:0 git.fetch.wants=d9a7c66bd00e9fc74c41d266132b2171a7a82cdd git.fetch.haves.count=0 git.fetch.deepen=0 git.fetch.thin_pack=false git.fetch.ofs_delta=true git.protocol.version=2 git.pkt.frames=4 git.pkt.data=3 git.pkt.flush=1 git.pkt.delim=0 git.pkt.bytes=227 git.pkt.payload.max=200 git.sideband.band1.bytes=200 git.sideband.band2.bytes=0 git.sideband.band3.bytes=0 git.pack.objects=1 git.pack.bytes=200 git.pack.trailer=19b86a461d3d30a55c16a56ca10faa7dc7d8b30dOpen pack map
fetchtree:0200136 B · hit3 ms
git.upload-pack fetch http.response.status_code=200 git.upstream.cf_ray=- git.upstream.phase=fetch git.upstream.dur_ms=200 git.response.bytes=136 git.response.cache=HIT git.response.duration_ms=3 git.fetch.filter=tree:0 git.fetch.wants=417aee58b2825878b951f7f6739908469c89caa4 git.fetch.haves.count=0 git.fetch.deepen=0 git.fetch.thin_pack=false git.fetch.ofs_delta=true git.protocol.version=2 git.pkt.frames=4 git.pkt.data=3 git.pkt.flush=1 git.pkt.delim=0 git.pkt.bytes=136 git.pkt.payload.max=109 git.sideband.band1.bytes=109 git.sideband.band2.bytes=0 git.sideband.band3.bytes=0 git.pack.objects=1 git.pack.bytes=109 git.pack.trailer=ef7a178af4c886044b197f966ebdc9429f58f968Open pack map
fetch2004.2 KiB200 ms
git.upload-pack fetch http.response.status_code=200 git.response.bytes=4321 git.response.cache=MISS git.response.duration_ms=200 git.fetch.wants=cb0b0dd0fc3bf04358456e5d5a23a04df4fa728d git.fetch.haves.count=0 git.fetch.deepen=0 git.fetch.thin_pack=false git.fetch.ofs_delta=true git.protocol.version=2 git.pkt.frames=4 git.pkt.data=3 git.pkt.flush=1 git.pkt.delim=0 git.pkt.bytes=4321 git.pkt.payload.max=4294 git.sideband.band1.bytes=4294 git.sideband.band2.bytes=0 git.sideband.band3.bytes=0
Each row is one HTTP round trip ply made to the git server for this page, on one timeline. discover asks what the server speaks, ls-refs lists branch tips, fetch brings objects by id. A hit was served by Workers Cache. Tap a row for its wire details.
- Remote
- https://gitlab.com/gitlab-org/cli
- Ref
- refs/heads/main
- Commit
- 0dd7574dce9e385c5c30540e6c15657adc6bdce9
- cf-ray
- a5e2d940986f14c2
- Request
- e2982671…
- Protocol
- v2 · sha1
- Agent
- git/2.56.g1891de4-Linux
- Filter
- advertised
- Fetch
- shallow wait-for-done filter
- Capabilities
- agent ls-refs fetch server-option object-format