Clarify use cases for runCmd

[davetapley]

I found this action because I wanted to use my devcontainer in an Action.

At first this Action seemed like exactly what I needed, but I got stuck with #302.
That led me to realize I should use this Action to build the image:

jobs:
    build:
      name: Pre-build dev container image
      runs-on: ubuntu-latest
      steps:
        - name: Checkout
          uses: actions/checkout@v3

        - name: Login to GitHub Container Registry
          uses: docker/login-action@v2 
          with:
            registry: ghcr.io
            username: ${{ github.repository_owner }}
            password: ${{ secrets.GITHUB_TOKEN }}

        - name: Pre-build dev container image
          uses: devcontainers/ci@v0.3
          with:
              imageName: ghcr.io/foo/bar
              cacheFrom: ghcr.io/foo/bar
              push: 'always'

---

But then for actually running steps inside the container you can use jobs.<job_id>.container instead of runCmd:

jobs:
  deploy:
    name: Deploy
    runs-on: ubuntu-latest
    container:
      image: ghcr.io/foo/bar:latest
      credentials:
         username: ${{ github.actor }}
         password: ${{ secrets.GITHUB_TOKEN }}
      options: --privileged

    steps:
        - uses: actions/checkout@v3

Note that also allows me to use options: --privileged (for kota65535/github-openvpn-connect-action#40 (comment)).

---

So, question: Why would someone use runCmd, just to save time?
And if so can the readme / docs clarify that jobs.<job_id>.container is another option.

[anton-matosov]

I personally have two distinct cases for runCmd:

1. After building the devcontainer run build and tests within in as a sanity check that container functions correctly with PR changes. Aka a real CI for the devcontainer functionality itself
2. To run a single step in the devcontainer or run different steps in different containers. This is probably not the intended use case but works ok (no caching on agents, so it is slower compared to jobs.container in general)

https://github.com/devcontainers/ci/blob/main/action.yml says

  runCmd:
    required: false
    description: Specify the command to run after building the dev container image. Can be omitted to skip starting the container.

which I interpret as a fit for use case 1 above

[sireeshajonnalagadda]

Hi @davetapley,
Thank you for reaching out!
Good to hear that the workflow solves your caching issue #302

1. runCmd – Post-Container Build Command (for Dev Containers)

runCmd is commonly used in scenarios where you want to automatically execute commands to set up the environment within the container after it has been built. This is especially useful for things like:

• Installing dependencies that might be specific to the container environment.
• Running setup scripts for initializing databases, queues, or services.
• Running code generation scripts or other pre-configured setup that ensures your container is ready to be used for development.

Example Use Case:
Imagine you're working with a development container that requires a certain service (like a database or a local server) to run once the container starts. You could use runCmd to automatically start that service after the container is built and running.

2. jobs.<job_id>.container – Running Commands During GitHub Actions Jobs

Example Use Case:
CI/CD pipeline
For running tests or building your application within a specific container image during your CI pipeline, you can use jobs.<job_id>.container

I hope this clarifies the use of runcmd.
please feel free to reach out in case of further queries.

Thanks,
Sireesha

[sireeshajonnalagadda]

Closing this issue due to inactivity over the past two weeks. Feel free to reopen it if you have any questions or updates.