feat: Add userDataCommands to Ec2RunnerProvider

[GilUpstream]

Summary

Adds a userDataCommands prop to Ec2RunnerProvider that runs custom commands on instance start-up, before the runner registers with GitHub and starts the job.

Motivation: some software requires per-instance setup and can't simply be baked into the AMI with image builder components — for example security agents (Lacework, in my case) that need to register each instance. Today the EC2 user data template is hard-coded, so there's no supported way to do this.

Implementation notes

• Commands are inserted into the existing Linux/Windows user data templates via a placeholder, after initial setup and before the heartbeat/runner registration. They run as root on Linux (bash) and administrator on Windows (PowerShell).
• Since the templates go through States.Format, braces in user commands are escaped so things like ${VAR} are treated literally and never as placeholders. The replacement uses a replacer function so $ sequences in commands aren't mangled by String.replace special patterns.
• Providers with custom commands get a unique $.consts key (suffixed with node.addr) so multiple EC2 providers with different commands don't trip the duplicate-constants check. Providers without custom commands keep sharing the existing ec2UserDataLinux/ec2UserDataWindows keys.
• The prop docs steer users toward image builder components when per-instance setup isn't required, since start-up commands delay every job.

Testing

• New unit tests cover: no commands (template unchanged, placeholder removed), Linux and Windows command injection and ordering, brace/$ escaping, placeholder preservation, and multiple providers with different commands merging into one state machine without duplicate-key errors.
• Full test suite passes (220 tests), jsii compile and eslint clean, API.md regenerated with docgen.

Made with Cursor

[kichik]

Thanks.

You should already be able to add commands that run before the job with something like:

const builder = EcsRunnerProvider.imageBuilder(stack, 'builder');
builder.addComponent(
  RunnerImageComponent.environmentVariables({
    ACTIONS_RUNNER_HOOK_JOB_STARTED: '/home/runner/runner-started.sh',
  }),
);
builder.addComponent(
  RunnerImageComponent.custom({
    name: 'runner-started.sh',
    assets: [
      {
        source: 'INSERT_LOCAL_PATH_TO_STARTUP_SCRIPT_HERE', // TODO TODO TODO
        target: '/home/runner/runner-started.sh',
      },
    ],
  }),
);

const provider = new EcsRunnerProvider(stack, 'ECS', {
  labels: ['ecs'],
  imageBuilder: builder,
});

This method works on all types of providers and also has the added benefit of showing its output as part of the job for easier debugging.

For things like security agents, I'd personally prefer having the AMI bake a systemd unit preconfigured to start with the system. That way it can monitor everything including runner setup and even the existing userdata itself.

In general I worry about adding anything to our userdata. It's quite finicky with the braces and everything as you've mentioned.

Is there a use-case I'm not thinking of that would require userdata modification?

[GilUpstream]

@kichik That's a good workaround for this. Thanks! I've also actually got another issue now around tags, so I'll open a PR for that soon.