GitHub Version Tags
GitHub Actions allows you to perform numerous tasks automatically, including using the cURL command to insert a new tag when a release is made or when a pull request is closed for example.
This tutorial demonstrates how to build an automation that will create a new tag in Coralogix upon publishing a new release of your code.
Coralogix Version Tags API Endpoint
This document includes cluster-dependent URLs.
Choose the https://api./api/v1/external/tags endpoint that corresponds to your Coralogix domain using the domain selector at the top of the page.
Tutorial
STEP 1. Create your Action as a .yml file inside our repository in the workflows directory .github/workflows/my-tag-automation.yml.
Note:
- Remember to place the .github folder inside the root folder of your repository.
STEP 2. Add the content of your action.
- Add the name of the automation and the events that activate it.
name: "Create a tag"
on:
release:
types: [published]
- Add the 'job' of our automation -- the action that it will execute.
name: "Create a tag"
on:
release:
types: [published]
jobs:
run-updater:
runs-on: ubuntu-latest
steps:
- name: create a tag
run: |
curl --location --request POST 'https://api.eu2.coralogix.com/api/v1/external/tags' \
--header 'Authorization: Bearer <cx_api_key>' \
--header 'Content-Type: application/json' \
--data-raw '{
"name": "'"${GITHUB_REF##*/}"'",
"application": ["<my_app>"],
"subsystem": ["<my_subsystem>"]
}'
${GITHUB_REF##*/} = a github action variable holding the reference of the action , in this context its the tag of the release.
<my_app> - Your Application name. You can input more than one name, use the comma delimiter ‘,’ between the names.
<my_subsystem> - Your Subsystem name. You can input more than one name, use the comma delimiter ‘,’ between the names.
<cluster_endpoint> - Choose the https://api./api/v1/external/tags endpoint that corresponds to your Coralogix domain using the domain selector at the top of the page.
<cx_api_key> - To use this API you need to create a personal or team API key. It’s recommended to use permission presets, as they are automatically updated with all relevant permissions. Alternatively, you can manually add individual permissions.
| Preset | Action | Description |
|---|---|---|
| CICDIntegration | VERSION-BENCHMARK-TAGS:READ VERSION-BENCHMARKS-REPORTS:READ VERSION-BENCHMARK-TAGS:UPDATE | View Version Benchmark Tags View Version Benchmark Reports Modify Version Benchmark Tags |
STEP 3. After publishing a new release, the Action will run, and a new tag in Coralogix will be created.
Send deployment events
Send each deployment to the Coralogix ops events API as well, and it appears as an event marker on your APM charts, so you can line a latency or error-rate change up with the workflow run that caused it.
What you need
- A Send Your Data API key with the OpsEvents role preset. The ops events API rejects any other key type or preset, including the
CICDIntegrationkey used for version tags, with403 Forbidden. - The ops events endpoint for your Coralogix domain. Use the domain selector at the top of this page to resolve it: https://api./v1/ops-events
- The service name and environment exactly as they appear in APM. They must equal the
service.nameanddeployment.environment.nameresource attributes your service reports. An event that matches no service is still stored, but appears only under All events.
Add the step to your workflow
Store the API key as a repository secret named CX_OPS_EVENTS_API_KEY, then add this step as the last step of your deployment job. if: always() makes it run when the deployment fails too, and reports the job's result.
- name: Send deployment event to Coralogix
if: always()
env:
CX_API_KEY: ${{ secrets.CX_OPS_EVENTS_API_KEY }}
SERVICE_NAME: <service_name>
ENVIRONMENT: <environment>
JOB_STATUS: ${{ job.status }}
run: |
case "$JOB_STATUS" in
success) STATUS=PIPELINE_RESULT_STATUS_SUCCESS ;;
cancelled) STATUS=PIPELINE_RESULT_STATUS_CANCELLATION ;;
*) STATUS=PIPELINE_RESULT_STATUS_FAILURE ;;
esac
if [ "$GITHUB_REF_TYPE" = tag ]; then REF_TYPE=VCS_REF_TYPE_TAG; else REF_TYPE=VCS_REF_TYPE_BRANCH; fi
curl -sS --fail-with-body -X POST 'https://api.eu2.coralogix.com/v1/ops-events' \
-H "Authorization: Bearer $CX_API_KEY" \
-H 'Content-Type: application/json' \
--data-binary @- <<EOF
{
"opsEvent": {
"timestamp": "$(date -u +%Y-%m-%dT%H:%M:%SZ)",
"description": "$SERVICE_NAME $GITHUB_SHA deployed to $ENVIRONMENT",
"attributes": {
"service": { "name": "$SERVICE_NAME" },
"environment": "$ENVIRONMENT"
},
"cdEvent": {
"system": "CD_SYSTEM_GITHUB",
"pipeline": {
"name": "$GITHUB_WORKFLOW",
"run": {
"id": "$GITHUB_RUN_ID",
"url": "$GITHUB_SERVER_URL/$GITHUB_REPOSITORY/actions/runs/$GITHUB_RUN_ID"
},
"result": { "status": "$STATUS" },
"task": { "name": "$GITHUB_JOB", "type": "PIPELINE_TASK_TYPE_DEPLOY" }
},
"vcs": {
"system": "VCS_SYSTEM_GITHUB",
"type": "$REF_TYPE",
"repository": {
"name": "$GITHUB_REPOSITORY",
"url": "$GITHUB_SERVER_URL/$GITHUB_REPOSITORY"
},
"ref": { "head": { "name": "$GITHUB_REF_NAME", "revision": "$GITHUB_SHA" } }
}
}
}
}
EOF
Replace <service_name> and <environment> with the values from APM. cdEvent.system and cdEvent.pipeline.name are required; the API rejects a cdEvent without them.
A successful request returns the server-generated event id. The marker then appears on the service's APM charts; see Event markers for how to show it and for the full field reference. The API rejects a timestamp more than 24 hours from the time the request is received, so send the event from the pipeline as it runs rather than backfilling.