Update README.md and docs (#10)

Co-authored-by: goruha <[email protected]>
cloudposse · Dec 7, 2022 · 67598d0 · 67598d0
1 parent 5e8b431
commit 67598d0
Showing 1 changed file with 136 additions and 38 deletions.
diff --git a/README.md b/README.md
@@ -1,6 +1,6 @@
 
 <!-- markdownlint-disable -->
-# example-github-action-composite [![Latest Release](https://img.shields.io/github/release/cloudposse/example-github-action-composite.svg)](https://github.com/cloudposse/example-github-action-composite/releases/latest) [![Slack Community](https://slack.cloudposse.com/badge.svg)](https://slack.cloudposse.com)
+# github-action-docker-promote [![Latest Release](https://img.shields.io/github/release/cloudposse/github-action-docker-promote.svg)](https://github.com/cloudposse/github-action-docker-promote/releases/latest) [![Slack Community](https://slack.cloudposse.com/badge.svg)](https://slack.cloudposse.com)
 <!-- markdownlint-restore -->
 
 [![README Header][readme_header_img]][readme_header_link]
@@ -28,7 +28,7 @@
 
 -->
 
-Template repository of composite GitHub Action
+Promote docker image
 
 ---
 
@@ -58,8 +58,8 @@ It's 100% Open Source and licensed under the [APACHE2](LICENSE).
 
 ## Introduction
 
-This is template repository to create composite GitHub Actions. 
-Feel free to use it as reference and starting point.
+Promote Docker image to specific tags provided explicitly or implicitly with 
+[Docker Metadata action](https://github.com/marketplace/actions/docker-metadata-action)  
 
 
 
@@ -69,6 +69,45 @@ Feel free to use it as reference and starting point.
 
 
 
+### Promote a docker image to specific tag
+
+```yaml
+  name: Release
+  on:
+    release:
+      types: [published]
+
+  permissions:
+    id-token: write
+    contents: write
+
+  jobs:
+    promote:
+      runs-on: ubuntu-latest
+      steps:
+        - name: Docker image promote
+          uses: cloudposse/github-action-docker-promote@main
+          id: promote
+          with:
+            registry: registry.hub.docker.com
+            organization: ${{ github.event.repository.owner.login }}
+            repository: ${{ github.event.repository.name }}
+            login: ${{ secrets.DOCKERHUB_USERNAME }}
+            password: ${{ secrets.DOCKERHUB_PASSWORD }}
+            from: sha-${{ github.sha }}
+            to: ${{ github.event.release.tag_name }}
+            use_metadata: false
+
+      outputs:
+        image: ${{ steps.promote.outputs.image }}
+        tag: ${{ steps.promote.outputs.tag }}  
+```
+  
+### Promote a docker image to tags detected from metadata
+
+Promote action use [Docker Metadata action](https://github.com/marketplace/actions/docker-metadata-action) under the 
+hood and can detect `to` tags based on Git reference and GitHub events. 
+
 ```yaml
   name: Pull Request
   on:
@@ -80,14 +119,70 @@ Feel free to use it as reference and starting point.
     context:
       runs-on: ubuntu-latest
       steps:
-        - name: Example action
-          uses: cloudposse/example-github-action-composite@main
-          id: example
+
+        - name: Checkout
+          uses: actions/checkout@v3
+          with:
+            fetch-depth: 2
+
+        - name: Get previous commit
+          id: prev-commit
+          run: echo "sha=$(git rev-parse --verify HEAD^1)" >> $GITHUB_OUTPUT
+
+        - name: Docker image promote
+          uses: cloudposse/github-action-docker-promote@main
+          id: promote
+          with:
+            registry: registry.hub.docker.com
+            organization: ${{ github.event.repository.owner.login }}
+            repository: ${{ github.event.repository.name }}
+            login: ${{ secrets.DOCKERHUB_USERNAME }}
+            password: ${{ secrets.DOCKERHUB_PASSWORD }}
+            from: sha-${{ steps.prev-commit.outputs.sha }}
+            use_metadata: true
+
+      outputs:
+        image: ${{ steps.promote.outputs.image }}
+        tag: ${{ steps.promote.outputs.tag }}  
+```
+
+### Promote a docker image with `from` fetched from metadata
+
+If you skip `from` tag then it would be populated as SHA of the current commit in long format.
+
+```yaml
+  name: Release
+  on:
+    release:
+      types: [published]
+
+  permissions:
+    id-token: write
+    contents: write
+
+  jobs:
+    promote:
+      runs-on: ubuntu-latest
+      steps:
+        - name: Checkout
+          uses: actions/checkout@v3
+
+        - name: Docker image promote
+          uses: cloudposse/github-action-docker-promote@main
+          id: promote
           with:
-            param1: true
+            registry: registry.hub.docker.com
+            organization: ${{ github.event.repository.owner.login }}
+            repository: ${{ github.event.repository.name }}
+            login: ${{ secrets.DOCKERHUB_USERNAME }}
+            password: ${{ secrets.DOCKERHUB_PASSWORD }}
+            ## `from` is long SHA
+            to: ${{ github.event.release.tag_name }}
+            use_metadata: true
 
       outputs:
-        result: ${{ steps.example.outputs.result1 }}
+        image: ${{ steps.promote.outputs.image }}
+        tag: ${{ steps.promote.outputs.tag }}  
 ```
 
 
@@ -123,7 +218,7 @@ Feel free to use it as reference and starting point.
 
 ## Share the Love
 
-Like this project? Please give it a ★ on [our GitHub](https://github.com/cloudposse/example-github-action-composite)! (it helps us **a lot**)
+Like this project? Please give it a ★ on [our GitHub](https://github.com/cloudposse/github-action-docker-promote)! (it helps us **a lot**)
 
 Are you using this project or any of our other projects? Consider [leaving a testimonial][testimonial]. =)
 
@@ -133,12 +228,15 @@ Are you using this project or any of our other projects? Consider [leaving a tes
 
 Check out these related projects.
 
+- [github-action-docker-build-push](https://github.com/cloudposse/github-action-docker-build-push) - Build Docker image and push it
+- [github-action-docker-image-exists](https://github.com/cloudposse/github-action-docker-image-exists) - Check if docker image exists by pulling it
 
 
 ## References
 
 For additional context, refer to some of these links.
 
+- [docker-metadata-action](https://github.com/marketplace/actions/docker-metadata-action) - GitHub Action to extract metadata from Git reference and GitHub events.
 - [github-actions-workflows](https://github.com/cloudposse/github-actions-workflows) - Reusable workflows for different types of projects
 - [example-github-action-release-workflow](https://github.com/cloudposse/example-github-action-release-workflow) - Example application with complicated release workflow
 
@@ -147,7 +245,7 @@ For additional context, refer to some of these links.
 
 **Got a question?** We got answers.
 
-File a GitHub [issue](https://github.com/cloudposse/example-github-action-composite/issues), send us an [email][email] or join our [Slack Community][slack].
+File a GitHub [issue](https://github.com/cloudposse/github-action-docker-promote/issues), send us an [email][email] or join our [Slack Community][slack].
 
 [![README Commercial Support][readme_commercial_support_img]][readme_commercial_support_link]
 
@@ -195,7 +293,7 @@ Sign up for [our newsletter][newsletter] that covers everything on our technolog
 
 ### Bug Reports & Feature Requests
 
-Please use the [issue tracker](https://github.com/cloudposse/example-github-action-composite/issues) to report any bugs or file feature requests.
+Please use the [issue tracker](https://github.com/cloudposse/github-action-docker-promote/issues) to report any bugs or file feature requests.
 
 ### Developing
 
@@ -283,33 +381,33 @@ Check out [our other projects][github], [follow us on twitter][twitter], [apply
 [![Beacon][beacon]][website]
 <!-- markdownlint-disable -->
   [logo]: https://cloudposse.com/logo-300x69.svg
-  [docs]: https://cpco.io/docs?utm_source=github&utm_medium=readme&utm_campaign=cloudposse/example-github-action-composite&utm_content=docs
-  [website]: https://cpco.io/homepage?utm_source=github&utm_medium=readme&utm_campaign=cloudposse/example-github-action-composite&utm_content=website
-  [github]: https://cpco.io/github?utm_source=github&utm_medium=readme&utm_campaign=cloudposse/example-github-action-composite&utm_content=github
-  [jobs]: https://cpco.io/jobs?utm_source=github&utm_medium=readme&utm_campaign=cloudposse/example-github-action-composite&utm_content=jobs
-  [hire]: https://cpco.io/hire?utm_source=github&utm_medium=readme&utm_campaign=cloudposse/example-github-action-composite&utm_content=hire
-  [slack]: https://cpco.io/slack?utm_source=github&utm_medium=readme&utm_campaign=cloudposse/example-github-action-composite&utm_content=slack
-  [linkedin]: https://cpco.io/linkedin?utm_source=github&utm_medium=readme&utm_campaign=cloudposse/example-github-action-composite&utm_content=linkedin
-  [twitter]: https://cpco.io/twitter?utm_source=github&utm_medium=readme&utm_campaign=cloudposse/example-github-action-composite&utm_content=twitter
-  [testimonial]: https://cpco.io/leave-testimonial?utm_source=github&utm_medium=readme&utm_campaign=cloudposse/example-github-action-composite&utm_content=testimonial
-  [office_hours]: https://cloudposse.com/office-hours?utm_source=github&utm_medium=readme&utm_campaign=cloudposse/example-github-action-composite&utm_content=office_hours
-  [newsletter]: https://cpco.io/newsletter?utm_source=github&utm_medium=readme&utm_campaign=cloudposse/example-github-action-composite&utm_content=newsletter
-  [discourse]: https://ask.sweetops.com/?utm_source=github&utm_medium=readme&utm_campaign=cloudposse/example-github-action-composite&utm_content=discourse
-  [email]: https://cpco.io/email?utm_source=github&utm_medium=readme&utm_campaign=cloudposse/example-github-action-composite&utm_content=email
-  [commercial_support]: https://cpco.io/commercial-support?utm_source=github&utm_medium=readme&utm_campaign=cloudposse/example-github-action-composite&utm_content=commercial_support
-  [we_love_open_source]: https://cpco.io/we-love-open-source?utm_source=github&utm_medium=readme&utm_campaign=cloudposse/example-github-action-composite&utm_content=we_love_open_source
-  [terraform_modules]: https://cpco.io/terraform-modules?utm_source=github&utm_medium=readme&utm_campaign=cloudposse/example-github-action-composite&utm_content=terraform_modules
+  [docs]: https://cpco.io/docs?utm_source=github&utm_medium=readme&utm_campaign=cloudposse/github-action-docker-promote&utm_content=docs
+  [website]: https://cpco.io/homepage?utm_source=github&utm_medium=readme&utm_campaign=cloudposse/github-action-docker-promote&utm_content=website
+  [github]: https://cpco.io/github?utm_source=github&utm_medium=readme&utm_campaign=cloudposse/github-action-docker-promote&utm_content=github
+  [jobs]: https://cpco.io/jobs?utm_source=github&utm_medium=readme&utm_campaign=cloudposse/github-action-docker-promote&utm_content=jobs
+  [hire]: https://cpco.io/hire?utm_source=github&utm_medium=readme&utm_campaign=cloudposse/github-action-docker-promote&utm_content=hire
+  [slack]: https://cpco.io/slack?utm_source=github&utm_medium=readme&utm_campaign=cloudposse/github-action-docker-promote&utm_content=slack
+  [linkedin]: https://cpco.io/linkedin?utm_source=github&utm_medium=readme&utm_campaign=cloudposse/github-action-docker-promote&utm_content=linkedin
+  [twitter]: https://cpco.io/twitter?utm_source=github&utm_medium=readme&utm_campaign=cloudposse/github-action-docker-promote&utm_content=twitter
+  [testimonial]: https://cpco.io/leave-testimonial?utm_source=github&utm_medium=readme&utm_campaign=cloudposse/github-action-docker-promote&utm_content=testimonial
+  [office_hours]: https://cloudposse.com/office-hours?utm_source=github&utm_medium=readme&utm_campaign=cloudposse/github-action-docker-promote&utm_content=office_hours
+  [newsletter]: https://cpco.io/newsletter?utm_source=github&utm_medium=readme&utm_campaign=cloudposse/github-action-docker-promote&utm_content=newsletter
+  [discourse]: https://ask.sweetops.com/?utm_source=github&utm_medium=readme&utm_campaign=cloudposse/github-action-docker-promote&utm_content=discourse
+  [email]: https://cpco.io/email?utm_source=github&utm_medium=readme&utm_campaign=cloudposse/github-action-docker-promote&utm_content=email
+  [commercial_support]: https://cpco.io/commercial-support?utm_source=github&utm_medium=readme&utm_campaign=cloudposse/github-action-docker-promote&utm_content=commercial_support
+  [we_love_open_source]: https://cpco.io/we-love-open-source?utm_source=github&utm_medium=readme&utm_campaign=cloudposse/github-action-docker-promote&utm_content=we_love_open_source
+  [terraform_modules]: https://cpco.io/terraform-modules?utm_source=github&utm_medium=readme&utm_campaign=cloudposse/github-action-docker-promote&utm_content=terraform_modules
   [readme_header_img]: https://cloudposse.com/readme/header/img
-  [readme_header_link]: https://cloudposse.com/readme/header/link?utm_source=github&utm_medium=readme&utm_campaign=cloudposse/example-github-action-composite&utm_content=readme_header_link
+  [readme_header_link]: https://cloudposse.com/readme/header/link?utm_source=github&utm_medium=readme&utm_campaign=cloudposse/github-action-docker-promote&utm_content=readme_header_link
   [readme_footer_img]: https://cloudposse.com/readme/footer/img
-  [readme_footer_link]: https://cloudposse.com/readme/footer/link?utm_source=github&utm_medium=readme&utm_campaign=cloudposse/example-github-action-composite&utm_content=readme_footer_link
+  [readme_footer_link]: https://cloudposse.com/readme/footer/link?utm_source=github&utm_medium=readme&utm_campaign=cloudposse/github-action-docker-promote&utm_content=readme_footer_link
   [readme_commercial_support_img]: https://cloudposse.com/readme/commercial-support/img
-  [readme_commercial_support_link]: https://cloudposse.com/readme/commercial-support/link?utm_source=github&utm_medium=readme&utm_campaign=cloudposse/example-github-action-composite&utm_content=readme_commercial_support_link
-  [share_twitter]: https://twitter.com/intent/tweet/?text=example-github-action-composite&url=https://github.com/cloudposse/example-github-action-composite
-  [share_linkedin]: https://www.linkedin.com/shareArticle?mini=true&title=example-github-action-composite&url=https://github.com/cloudposse/example-github-action-composite
-  [share_reddit]: https://reddit.com/submit/?url=https://github.com/cloudposse/example-github-action-composite
-  [share_facebook]: https://facebook.com/sharer/sharer.php?u=https://github.com/cloudposse/example-github-action-composite
-  [share_googleplus]: https://plus.google.com/share?url=https://github.com/cloudposse/example-github-action-composite
-  [share_email]: mailto:?subject=example-github-action-composite&body=https://github.com/cloudposse/example-github-action-composite
-  [beacon]: https://ga-beacon.cloudposse.com/UA-76589703-4/cloudposse/example-github-action-composite?pixel&cs=github&cm=readme&an=example-github-action-composite
+  [readme_commercial_support_link]: https://cloudposse.com/readme/commercial-support/link?utm_source=github&utm_medium=readme&utm_campaign=cloudposse/github-action-docker-promote&utm_content=readme_commercial_support_link
+  [share_twitter]: https://twitter.com/intent/tweet/?text=github-action-docker-promote&url=https://github.com/cloudposse/github-action-docker-promote
+  [share_linkedin]: https://www.linkedin.com/shareArticle?mini=true&title=github-action-docker-promote&url=https://github.com/cloudposse/github-action-docker-promote
+  [share_reddit]: https://reddit.com/submit/?url=https://github.com/cloudposse/github-action-docker-promote
+  [share_facebook]: https://facebook.com/sharer/sharer.php?u=https://github.com/cloudposse/github-action-docker-promote
+  [share_googleplus]: https://plus.google.com/share?url=https://github.com/cloudposse/github-action-docker-promote
+  [share_email]: mailto:?subject=github-action-docker-promote&body=https://github.com/cloudposse/github-action-docker-promote
+  [beacon]: https://ga-beacon.cloudposse.com/UA-76589703-4/cloudposse/github-action-docker-promote?pixel&cs=github&cm=readme&an=github-action-docker-promote
 <!-- markdownlint-restore -->