Update readme, make 'image' input required

Signed-off-by: Tim Etchells <tetchell@redhat.com>

README.md

@@ -1,4 +1,4 @@
-# buildah-action
+# buildah
 
 [![tag badge](https://img.shields.io/github/v/tag/redhat-actions/buildah-action?sort=semver)](https://github.com/redhat-actions/buildah-action/tags)
 [![license badge](https://img.shields.io/github/license/redhat-actions/buildah-action)](./LICENSE)
@@ -8,7 +8,7 @@ Buildah is a GitHub Action for building OCI-compatible (Docker- and Kubernetes-c
 
 Buildah action works only on Linux distributions, and it is not supported on Windows or Mac platforms at this time.
 
-Note that GitHub's [Ubuntu Environments](https://github.com/actions/virtual-environments#available-environments) (ubuntu-20.04 and ubuntu-18.04) come with buildah 1.17.0 installed. So, if you are not using those Ubuntu environments you need to make sure to install buildah tool in an early step.
+Note that GitHub's [Ubuntu Environments](https://github.com/actions/virtual-environments#available-environments) (ubuntu-20.04 and ubuntu-18.04) come with buildah 1.17.0 installed. If you are not using these environments, you must first [install buildah](https://github.com/containers/buildah/blob/master/install.md).
 
 ## Action Inputs
 
@@ -24,17 +24,20 @@ Note that GitHub's [Ubuntu Environments](https://github.com/actions/virtual-envi
   <tr>
     <td>image</td>
     <td>Yes</td>
-    <td>Name to give to the image that will be eventually created.</td>
+    <td>Name to give the output image.</td>
   </tr>
 
   <tr>
     <td>tag</td>
     <td>No</td>
-    <td>Tag to give to the image that will be eventually created (default: latest)</td>
+    <td>
+      Tag to give to the output image.<br>
+      Default: <code>latest</code>
+    </td>
   </tr>
 
   <tr>
-    <td>base-name</td>
+    <td>base-image</td>
     <td>No</td>
     <td>The base image to use to create the initial container. If not specified, the action will try to pick one automatically. (N.B: At this time the action is only able to auto select Java base image)</td>
   </tr>
@@ -42,25 +45,32 @@ Note that GitHub's [Ubuntu Environments](https://github.com/actions/virtual-envi
   <tr>
     <td>dockerfiles</td>
     <td>No</td>
-    <td>The list of Dockerfile paths to perform a build using docker instructions. This is a multiline input to add multiple values.</td>
+    <td>The list of Dockerfile paths to perform a build using docker instructions. This is a multiline input if you wish to add multiple Dockerfiles.
+    </td>
   </tr>
 
   <tr>
     <td>context</td>
     <td>No</td>
-    <td>The path of the directory to use as context (default: .)</td>
+    <td>Path to directory to use as the build context.<br>
+    Default: <code>.</code></td>
   </tr>
 
   <tr>
     <td>content</td>
     <td>No</td>
-    <td>The content to copy inside the container to create the final image. This is a multiline input to allow you to copy more than one file/directory. For example - <br> content: | <br> target/spring-petclinic-2.3.0.BUILD-SNAPSHOT.jar</td>
+    <td>The content to copy inside the container to create the final image. This is a multiline input to allow you to copy more than one file/directory.<br>
+    <pre>content: |
+  target/spring-petclinic-2.3.0.BUILD-SNAPSHOT.jar</pre>
+    </td>
   </tr>
 
   <tr>
     <td>entrypoint</td>
     <td>No</td>
-    <td>The entry point to set for the container. This is a multiline input to add multiple values. For example - <br> entrypoint: | <br> java <br> -jar <br> spring-petclinic-2.3.0.BUILD-SNAPSHOT.jar</td>
+    <td>The entry point to set for the container. Can split arguments across multiple lines if desired.
+      <pre>entrypoint: java -jar spring-petclinic-2.3.0.BUILD-SNAPSHOT.jar</pre>
+    </td>
   </tr>
 
   <tr>
@@ -70,7 +80,7 @@ Note that GitHub's [Ubuntu Environments](https://github.com/actions/virtual-envi
   </tr>
 
   <tr>
-    <td>working-dir</td>
+    <td>workdir</td>
     <td>No</td>
     <td>The working directory to use within the container.</td>
   </tr>
@@ -78,18 +88,23 @@ Note that GitHub's [Ubuntu Environments](https://github.com/actions/virtual-envi
   <tr>
     <td>envs</td>
     <td>No</td>
-    <td>The environment variables to be set when running the container. This is a multiline input to add multiple environment variables.For example - <br> envs: | <br> GOPATH=/root/buildah</td>
+    <td>The environment variables to be set when running the container. This is a multiline input to add multiple environment variables.<br>
+      <pre>
+envs: |
+  GOPATH=/root/buildah/go</pre>
+    </td>
   </tr>
 </table>
 
-## Build an image using Dockerfile or from scratch 
+## Build Types
 
-One of the advantages of using the `buildah` action is that you can decide the way you want to build your image. 
+You can configure the `buildah` action to build your image using one or more Dockerfiles, or from scratch.
 
-If you have been using Docker and have some existing Dockerfiles, `buildah` is able to build images by using them.
+### Building using Docker
-In this case the inputs needed are just `image`, `dockerfiles` and `content`.
 
-An example below
+If you have been using Docker and have an existing Dockerfile, `buildah` can reuse your dockerfile.
+
+In this case the inputs needed are `image` and `dockerfiles`. `tag` is also recommended.
 
 ```yaml
 name: Build Image using Dockerfile
@@ -101,49 +116,55 @@ jobs:
     runs-on: ubuntu-latest
 
     steps:
-    - name: Checkout
+    - uses: actions/checkout@v2
-      uses: actions/checkout@v2
+
     - name: Buildah Action
       uses: redhat-actions/buildah-action@v1
       with:
-        image: awesome-name:v1
+        image: my-new-image
+        tag: v1
         dockerfiles: |
           ./Dockerfile
 ```
 
-On the other hand, a build from scratch may require more inputs as it needs to execute a series of steps that can be summarized in:
+### Building from scratch
-- Create a new container by using the base image (input: `base-image`)
-- Copy all files/directories inside the newly-created container (input: `content`)
-- Set up the image configuration values (inputs: `entrypoint`,`port`,`envs`)
-- Build an optimized image
 
-Example of building a Spring Boot Java app image below
+Building from scratch requires more inputs, that would normally be specified in the Dockerfile.
 
+Do not set `dockerfiles` if you are doing a build from scratch, or a docker build will be performed, and the other inputs will be ignored.
+
+- An output `image` name and usually a `tag`.
+- `base-image`
+  - In a Dockerfile, this would be the `FROM` directive.
+- `content` to copy into the new image
+  - In a Dockerfile, this would be `COPY` directives.
+- `entrypoint` so the container knows what command to run.
+- All other optional configuration inputs.
+
+Example of building a Spring Boot Java app image:
 ```yaml
 name: Build Image
 on: [push]
 
 jobs:
-  build:
+  build-image:
     name: Build image
     runs-on: ubuntu-latest
 
     steps:
-    - name: Checkout
+    - uses: actions/checkout@v2
-      uses: actions/checkout@v2
 
-    - name: Maven
+    - run: mvn package
-      run: mvn package
+
-    - name: Build Action
+    - name: Build Image
       uses: redhat-actions/buildah-action@v1
       with:
-        image: awesome-name:v1
+        base-image: docker.io/fabric8/java-alpine-openjdk11-jre
+        image: my-new-image
+        tag: v1
         content: |
           target/spring-petclinic-2.3.0.BUILD-SNAPSHOT.jar
-        entrypoint: |
+        entrypoint: java -jar spring-petclinic-2.3.0.BUILD-SNAPSHOT.jar
-          java
-          -jar
-          spring-petclinic-2.3.0.BUILD-SNAPSHOT.jar
         port: 8080
 ```
 

action.yml

@@ -30,8 +30,8 @@ inputs:
     required: false
   port:
     description: 'The port to expose when running containers based on image'
-    required: false  
+    required: false
-  working-dir:
+  workdir:
     description: 'The working directory to use within the container'
     required: false
   envs:
@@ -39,4 +39,4 @@ inputs:
     required: false
 runs:
   using: 'node12'
-  main: 'dist/index.js'
+  main: 'dist/index.js'

src/index.ts

@@ -18,13 +18,13 @@ export async function run(): Promise<void> {
 
     const workspace = process.env['GITHUB_WORKSPACE'];
     let dockerFiles = getInputList('dockerfiles');
-    const newImage = `${core.getInput('image')}:${core.getInput('tag')}`;
+    const newImage = `${core.getInput('image', { required: true })}:${core.getInput('tag', { required: true })}`;
-    
+
     if (dockerFiles.length !== 0) {
-        doBuildUsingDockerFiles(cli, newImage, workspace, dockerFiles);        
+        doBuildUsingDockerFiles(cli, newImage, workspace, dockerFiles);
     } else {
         doBuildFromScratch(cli, newImage, workspace);
-    }    
+    }
 }
 
 async function doBuildUsingDockerFiles(cli: BuildahCli, newImage: string, workspace: string, dockerFiles: string[]): Promise<void> {
@@ -38,14 +38,14 @@ async function doBuildUsingDockerFiles(cli: BuildahCli, newImage: string, worksp
 
 async function doBuildFromScratch(cli: BuildahCli, newImage: string, workspace: string) {
     let baseImage = core.getInput('base-image');
-    const content = getInputList('content');    
+    const content = getInputList('content');
     const entrypoint = getInputList('entrypoint');
     const port = core.getInput('port');
-    const workingDir = core.getInput('working-dir');
+    const workingDir = core.getInput('workdir');
     const envs = getInputList('envs');
 
-    // if base-image is not specified by the user we need to pick one automatically 
+    // if base-image is not specified by the user we need to pick one automatically
-    if (!baseImage) {        
+    if (!baseImage) {
         if (workspace) {
             // check language/framework used and pick base-image automatically
             const languages = await recognizer.detectLanguages(workspace);
@@ -55,9 +55,9 @@ async function doBuildFromScratch(cli: BuildahCli, newImage: string, workspace:
             }
         } else {
             return Promise.reject(new Error('No base image found to create a new container'));
-        }        
+        }
     }
-    
+
     const container = await cli.from(baseImage);
     if (container.succeeded === false) {
         return Promise.reject(new Error(container.reason));
@@ -119,7 +119,7 @@ async function getBaseImageByLanguage(language: Language): Promise<string> {
     // eslint-disable-next-line no-undef
     const rawData = await fs.readFile(path.join(__dirname, '..', 'language-image.json'), 'utf-8');
     const languageImageJSON = JSON.parse(rawData);
-    return languageImageJSON[language.name];      
+    return languageImageJSON[language.name];
 }
 
-run().catch(core.setFailed);
+run().catch(core.setFailed);