Added a job update command to make changes to a job

[keithpitt]

This is a command that lets a job make changes to itself at runtime. The client doesn't know about what it can update, so it's pretty generic. We can add support for different attributes as we go.

The first attribute I'm supporting is label. This is useful if you want to call out something from inside a job, but don't want to a full blown annotation:

buildkite agent job update "label" " :warning::warning::warning:" --apend

• Send a change UUID so the backend make the changes idempotent

[lox]

This looks great! Will be interesting to see how folks use this.

[keithpitt]

@lox cool, thanks for the review. Will merge once I've pushed the backend for it 👌

[toolmantim]

I wonder if we need append, given we already have the label as an environment variable? And because some attributes might not be appendable?

[keithpitt]

(changing the label of the current job is a bit of a contrived example, because you're right, you already have $BUILDKITE_JOB_NAME floating around)

One cool thing about this API is that it can do things to other jobs that the agent has access to. So if you know the $BUILDKITE_JOB_UUID of another job, you could append to it's label (without having to know it's current label) Another possibility is that you can "append" a new agent agent rule to a job, or even "append" a new environment variable to it.

You're right in that some attributes might not be appendable, and I can handle that in a validation error message "you can't do that" and some docs.

[toolmantim]

Make sense! 👍🏼 I just wanted to ask, because it stood out as being a slightly awkward command line arg with the other properties, but it's not a big deal.

[keithpitt]

So I first called this job update, but I'd like to change it to step update, to align with the things you declare in your pipeline.yml file. Any major objections?

If you have a "tests.sh" step that fails, and you retry it, the step is still the same. We've just internally created a new job to represent the new work for it. The step is the "intention" of the work.

If you buildkite-agent step update in a parallel job, it'd make the change all the parallel jobs in the step.

This pipeline here demonstrates the concept well. With this sort of view, the "label" of the job doesn't really matter. The thing I actually want to change is the step label in the build pipeline.

More generally I want to make a clearer distinction between steps and jobs. A build has steps, and steps have jobs. The benefit of this layer is it gives us a great foundation for jobs that kick off to other jobs. Let's say your job is "run-this-script.sh", the step is "Run This Thing". The step shouldn't care that it created a job, which was then handed off to another agent to do the thing. All the build cares about, is if "run-this-script.sh" actually does it's thing (similar to what we've been talking about for a while @lox).

So there could very well be a job update command in the future, but for the use cases I'm aiming for with this plumbing, step update makes more sense.