action: faster docs PRs and branch protection gatekeeper (#409)

Author: v1v

.github/workflows/README.md

@@ -0,0 +1,43 @@
+## CI/CD
+
+There are 5 main stages that run on GitHub actions
+
+* Build
+* Lint
+* Notice
+* Test
+* Release
+
+There are some other stages that run for every push on the main branches:
+
+* [Smoke Tests](./smoke-tests.yml)
+
+### Scenarios
+
+* Pull Requests that are only affecting the docs files should not trigger any test or similar stages that are not required.
+* Builds do not get triggered automatically for Pull Requests from contributors that are not Elasticians when need to access to any GitHub Secrets.
+
+### How to interact with the CI?
+
+#### On a PR basis
+
+Once a PR has been opened then there are two different ways you can trigger builds in the CI:
+
+1. Commit based
+1. UI based, any Elasticians can force a build through the GitHub UI
+
+#### Branches
+
+Every time there is a merge to main or any release branches the whole workflow will compile and test every entry in the compatibility matrix for Linux and MacOS.
+
+#### Release process
+
+This process has been fully automated and it gets triggered when a tag release has been created, for further details please refers to the [release](../../RELEASE.md) docs.
+
+#### Smoke Tests
+
+You can run the [smoke-tests](https://github.com/elastic/apm-aws-lambda/actions/workflows/smoke-tests.yml) using the UI if needed.
+
+### OpenTelemetry
+
+There is a GitHub workflow in charge to populate what the workflow run in terms of jobs and steps. Those details can be seen in [here](https://ela.st/oblt-ci-cd-stats) (**NOTE**: only available for Elasticians).

.github/workflows/test-docs.yml

@@ -0,0 +1,27 @@
+# This workflow sets the test / ci status check to success in case it's a docs only PR and test.yml is not triggered
+# https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/defining-the-mergeability-of-pull-requests/troubleshooting-required-status-checks#handling-skipped-but-required-checks
+name: test # The name must be the same as in test.yml
+
+on:
+  pull_request:
+    paths-ignore: # This expression needs to match the paths ignored on main.yml.
+      - '**'
+      - '!**/*.md'
+      - '!**/*.asciidoc'
+      - '!**/*.png'
+
+permissions:
+  contents: read
+
+## Concurrency only allowed in the main branch.
+## So old builds running for old commits within the same Pull Request are cancelled
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: ${{ github.ref != 'refs/heads/main' }}
+
+jobs:
+  # dummy steps that allow to bypass those mandatory checks for tests
+  ci:
+    runs-on: ubuntu-latest
+    steps:
+      - run: 'echo "Not required for docs"'

.github/workflows/test.yml

@@ -1,14 +1,28 @@
 name: test
 
 on:
+  pull_request:
+    paths-ignore:
+      - "**/*.asciidoc"
+      - "**/*.md"
+      - "**/*.png"
   push:
     branches:
       - main
-  pull_request:
+    paths-ignore:
+      - "**/*.asciidoc"
+      - "**/*.md"
+      - "**/*.png"
 
 permissions:
   contents: read
 
+## Concurrency only allowed in the main branch.
+## So old builds running for old commits within the same Pull Request are cancelled
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: ${{ github.ref != 'refs/heads/main' }}
+
 jobs:
   test:
     strategy:
@@ -60,6 +74,20 @@ jobs:
       - uses: actions/checkout@v3
       - name: notice
         run: make check-notice
-        
-      
 
+  # The very last job to report whether the Workflow passed.
+  # This will act as the Branch Protection gatekeeper
+  ci:
+    if: always()
+    needs:
+      - build
+      - lint
+      - notice
+      - test
+    runs-on: ubuntu-latest
+    steps:
+      - id: check
+        uses: elastic/apm-pipeline-library/.github/actions/check-dependent-jobs@current
+        with:
+          needs: ${{ toJSON(needs) }}
+      - run: ${{ steps.check.outputs.isSuccess }}