This first post about GitHub Actions I covered the main terms used for that. Now, I'm adding notes considering the certification.

Series: Foundation> Copilot> Actions Overview> Dive in Actions

Index: Initial Conceptps > Security > Trigger Workflow > Runners > Marketplace > Variables > Workflow Command > Workflows > Actions > Manage for Enterprise



Initial Concepts

  • GitHub Actions is a continuous integration and continuous delivery (CI/CD) platform that allows build, test, and deployment automation. GitHub provides Linux, Windows, and macOS virtual machines to run your workflows, or you can host your own self-hosted runners in your own data center or cloud infrastructure [understand action]
  • Actions are the building blocks that power your workflow. [building blocks]
  • Components:
    • The workflow is triggered when an event occurs (e.g a pull request). The workflow contains one or more jobs which can run in sequential order or in parallel. Each job will run inside its own virtual machine runner, or inside a container, and has one or more steps that either run a script or run an action, which is a reusable extension that can simplify the workflow [components][about workflow][using jobs]
    • Jobs
      • Jobs run in parallel by default. To do in sequence use 'needs' which identify Dependent jobs [jobs]
      • Unlimited number of jobs
    • Steps
      • Steps represent individual tasks within a job. [jobs and steps]
      • You can use the if conditional to prevent a step from running unless a condition is met. It can be expression and use Functions[conditional][check functions]
      • The timeout-minutes keyword is used to set a maximum duration for the execution of individual commands within a step (Default: 360) [timeout]
      • GitHub adds two additional steps to each job to set up and complete the job's execution (Set up job and Complete job)[view logs] The Set up job step show the GITHUB_TOKEN permissions[token permission], Operation System and details of images (Runner Image section shows links to preinstalled Software) [preinstalled]
  • CI using GitHub Actions offers workflows that can build the code in your repository and run your tests [CI]
  • CD with GitHub Actions provides features that give you more control over deployments. It's possible use OpenID Connect (OIDC) to interact with cloud [CD]
  • You can use CLI. GitHub CLI is preinstalled on all GitHub-hosted runners. For each step that uses GitHub CLI, you must set an environment variable called GH_TOKEN to a token with the required scopes. [CLI]
  • You can use GitHub Actions workflows to run scripts. [scripts]



Security

  • GH gives support to OpenID Connect (OIDC) [about OIDC][api with oidc]
  • Controlling permissions for GITHUB_TOKEN. The GITHUB_TOKEN lasts until a job finishes or a maximum of 24 hours, whichever comes first [token][token auth]
  • Protection Rules:
    • Deployment Protection: Required reviewers,Deployment branches and tags, Allow administrators to bypass, require reviews before deployment, prevent self-reviews for deployment [manage env]
    • When a workflow job references an environment, the job won't start until all of the environment's protection rules pass [use env]
    • In case workflow requires review, if a job is rejected the workflow fails [approve and reject]
  • GitHub automatically redacts secrets printed to workflow logs by replacing them with placeholders. [secrets in logs]
  • To store secrets larger than 48 KB, you have to use encryption with GPG. The encrypted file is stored in the repository, and the decryption passphrase is stored as a secret on GitHub. [limits for secrets]
  • Programmatically access workflow logs: needs owner, repo, and run_id [download logs]
  • Automated release prioritizes security by ensuring that only dependencies are committed to tagged release commits and builds are performed during a release. [releasing and maintaining]
  • Encrypted secrets cannot be created at the workflow level. Workflows are specific to individual repositories and are used to define the automation tasks and processes for that repository. Secrets should be defined at a higher level of scope, such as organization, environment, or repository, to ensure proper access control and security. [using secrets]



Trigger Workflow

  • Workflow triggers are events that cause a workflow to run. These events occur in workflow's repository, outside of GitHub, manually or scheduled [about woarkflow][events trigger]
  • The 'on' keyword is used to specify the events (e.g push) that should trigger a workflow.[Events to trigger][trigger]
  • Steps [triggering workflows]:
    • An event occurs on a repository. The event has an associated commit SHA and Git ref.
    • GitHub searches the .github/workflows directory in the root of your repository for workflow files that are present in the associated commit SHA or Git ref of the event.
    • A workflow run is triggered for any workflows that have 'on:' values that match the triggering event.
    • Each workflow run will use the version of the workflow that is present in the associated commit SHA or Git ref of the event. When a workflow runs, GitHub sets the GITHUB_SHA (commit SHA) and GITHUB_REF (Git ref) environment variables.
  • The workflow can be triggered, for example, when an issue has been opened, edited, or milestoned; when a commit or a tag is pushed; when a repository is created from a template; when a discussion has been created, edited, or answered. [events trigger]
  • You can use activity types and filters to further control when your workflow will run. [event activity type][using filters]
    • In case the workflow has as filter both branches and paths filter, the workflow will only run when both branches and paths are satisfied.
    • The 'branches-ignore' can be used for exclusions.
    • The branch and branch-ignore can not be used for the same event. [target branch and ignore]
    • Use on.ENV_NAME.types to define the type of activity that will trigger a workflow run.[types]
  • If you want to manually trigger a specific job in a workflow, you can use an environment that requires approval from a specific team or user. [manual trigger]
  • issue_comment is an event when a comment is created on an issue [issue_comment]
  • The check_suite event in GitHub Actions is specifically designed to trigger workflow runs on the default branch of the repository. [check_suite]



Runners

  • jobs.job_id.runs-on [choose runner]
  • Types:
    • GitHub-hosted runner:
      • Each job runs in a fresh instance of a runner image specified by runs-on [standar hosted runner][about]
      • For jobs run on GitHub-hosted runners, Set up job records details of the runner image, and includes a link to the list of preinstalled tools that were present on the runner machine. [view logs]
    • Larger runner:
    • Self-hosted runner:
      • More control. It can be in a virtual machine or dedicated hardware [self-hosted runner][about]
      • Self-hosted runner can communicate through a proxy server configuring the proxy settings by environment variables: 'https_proxy: PROXY_URL_TRAFFIC'. [self-hosted proxy]
      • When troubleshooting connectivity issues with a self-hosted runner and validating its access to GitHub services, the development team must use the --check feature alongside the runner's URL and authentication token. [connectivity]
      • The primary purpose of custom labels for self-hosted runners is to route jobs to specific types of runners based on the labels assigned to those runners[label to route jobs]
      • Runner labels in GitHub Actions allow you to categorize different types of self-hosted runners based on their capabilities or workloads. By assigning labels to runners, you can easily incorporate them into workflows by specifying which runners should execute specific jobs based on their labels. [label felf-runner]
      • By default, self-hosted runners will automatically perform a software update whenever a new version of the runner software is available. [self-hosted updates]
      • Monitor the status of the self-hosted runners: offline, idle, active [checking status]
      • network requirement: permitting outbound connectivity to GitHub hosts using long polling [communication]
  • New runners are automatically assigned to a default group [move to a group]
  • Custom labels in GitHub Actions operate cumulatively, meaning a runner must have all assigned labels to be eligible to process a job. [custom labels]
  • Using a combination of GitHub-hosted and self-hosted runners can be beneficial when dealing with resource-intensive tasks. [hosted runner][self-hosted runner]
  • Runner groups help segregate runners based on team-specific expenses. Runner groups enable effective management and control over resources, ensuring cost allocation aligns with the organization's chargeback model [runner groups]



Marketplace

  • GitHub Marketplace is a central location for you to find actions created by the GitHub community. [marketplace action]
  • You can add the action you've created to the GitHub Marketplace by tagging it as a new release and then publishing it. [marketplace]
  • When drafting a new release and publishing an action to GitHub Marketplace, it is essential that the action's metadata file's category matches an existing GitHub Marketplace category [marketplace]
  • Publishing: [marketplace]
    • The action must be in a public repository
    • Each repository must contain a single action
    • The action's metadata file must be in the root directory
    • The name in the action's metadata file must be unique on the GitHub Marketplace
  • Steps: [steps to publish]
    • Add the action's metadata file to the repository root directory,
    • Draft a release,
    • Select "Publish this Action to the GitHub Marketplace,"
    • Choose categories,
    • Set a version tag,
    • Publish the release
  • How to decide to use or not an action: [automate tasks]
    • Review the action's action.yml file to make sure the code does what it says it does
    • Check if the action is verified in the GitHub Marketplace
    • Check if the action is in the GitHub Marketplace



Variables

  • Variable precedence: If a variable with the same name exists at multiple levels, the variable at the lowest level takes precedence. [variable precedence]
  • Naming convention [variable naming]
  • It is possible to use environment variables using the appropriate syntax for the shell you are using on the runner (e.g $NAME) or use contexts. The difference is that the context will be interpolated and replaced by a string before the job is sent to a runner. [context variable]
  • Passing values between steps and jobs [passing values] [passing info]
  • Context [about][event information]
  • Setting a default shell and working directory [default shell]
  • The ‘env’ key in the workflow file sets a custom environment variable for a single workflow. The scope of a custom variable set by this method is limited to the element in which it is defined. [def env variables]
  • Default Environment Variables: [default env variables][Def env variable]
    • They are all uppercase
    • They can only be used within the runner
    • They are not accessible through the env context. They can be accessed directly
    • They are set by GitHub and are available at every step in a workflow.
    • They provide information about the workflow run and repository.
    • The GITHUB_REPOSITORY default environment variable provides the owner and repository name (in the format owner/repository) for the repository where the workflow is running.
    • The RUNNER_OS environment variable provides the operating system of the runner executing the job. Possible values are Linux, Windows, or macOS.
    • The default environment variables starting with "GITHUB_" and "RUNNER_" cannot be overwritten using the GITHUB_ENV file in a workflow. [env. variables][workflow - default variables]
    • It is recommended that you use the default environment variables to reference the filesystem rather than using hard-coded file paths
    • The GITHUB_ACTIONS variable is used to determine whether the current workflow is running in GitHub Actions. It always evaluates to true when the workflow is running in the GitHub Actions environment, allowing you to conditionally execute certain steps or tasks based on this variable.
    • Setting ACTIONS_STEP_DEBUG to true can be configured as a secret or variable, with the value of the secret taking precedence. This allows for secure configuration of the debug logging setting while also providing the flexibility to override it with a variable if needed. [enabling debug]
  • When an input is specified in a workflow file or a default input value is used, GitHub converts input names to uppercase letters and replaces spaces with _ characters when creating the corresponding environment variable [specify inputs]



Workflow command

  • Workflow commands are used to interact with the runner during the execution of a step, providing a way to pass information, set environment variables, or perform other actions related to the workflow [workflow command][toolkit]
  • Send info to summary: echo "### Hello world! :rocket:" >> $GITHUB_STEP_SUMMARY [add summary]
  • Recommended practice for treating environment variables in GitHub Actions across different operating systems and shells: treat environment variables as case-sensitive [workflow commands]
  • GITHUB_PATH environment variable can be used to to add the a path (e.g. /tmp directory) to the PATH. It can be done using 'echo "/tmp" >> $GITHUB_PATH' [workflow commands]
  • The 'group' command in GitHub Actions allows you to group multiple workflow commands together under a specified name. This helps in organizing and structuring the workflow logs by grouping related commands, making it easier to identify and understand the different sections of the workflow. [grouping log lines]
  • The 'add-mask' command is used to mask sensitive information in the workflow logs, such as passwords or API keys, to prevent them from being exposed.
  • Workflow commands prefixed with the :: can be used to customize the runner environment, such as setting environment variables or modifying the working directory [commands]



Workflows

  • Workflow syntax: [syntax]
    • YAML: newlines and indentation; doesn’t allow literal tab characters for indentation.[YAML]
    • Reference action: Git ref, SHA, tag, or branch. [metadata syntax]
  • GitHub provides a token (unique GITHUB_TOKEN secret) that you can use to authenticate on behalf of GitHub Actions. [Token]
  • Avoid passing secrets between processes from the command line it can be visible [secrets]
  • One way to ensure that a script file is executable in a workflow job is to manually grant execute permission to the script file on the runner.
  • Jobs that reference an environment configured with required reviewers will wait for an approval before starting: Status -> 'Waiting'; and will fail in 30 days in case not approved[reviewing depyments]
  • Matrix:
    • The matrix strategy will generate a job for each combination of values from the specified dimensions. The matrix keyword is used within the strategy configuration of the job to define a matrix of different job configuration [matrix][variation of jobs]
    • GitHub limits the maximum number of jobs generated by a matrix to 256 jobs per workflow run [limits]
  • Cache
    • Caching dependencies helps reduce network utilization, runtime, and cost by avoiding the need to download dependencies for every workflow run [cache]
    • restore-keys allows you to specify a list of alternative restore keys. These keys are used sequentially in the order provided to find and restore a cache in case of a cache miss. [managing cache]
    • Use cache: The cache action in GitHub Actions automatically creates a new cache if a cache miss occurs during the workflow. This ensures that the necessary dependencies or artifacts are cached for future runs, improving the overall performance and efficiency of the workflow. [cache][manage cache]
  • Deploy in cloud [aws container][azure kubernates][google kubernetes]
  • Artifacts [storing and sharing data]
    • Custom retention periods can be configured for individual artifacts using the actions/upload-artifact action in a workflow [store artificat]
    • The expiration date of a specific artifact can be checked by the execution of a specific API call that retrieves the expiration date information associated with that artifact. The date can be checked by the 'expires_at' value returned by the “Actions” API [artifact]
    • Download the artifacts from the "Artifacts" section of the workflow run associated with the `build` job [download artifact]
    • The level of access required to download workflow artifacts is 'read' [download artifact]
    • once deleted, an artifact cannot be restored [removing]
  • You can view a GitHub Actions workflow run status for a pull request on the pull request before a merge, on the checks tab of the pull request and within the GitHub Actions tab of the repository [trigger]
  • The "Choose a workflow" page shows a selection of recommended starter workflows [starter workflows]
  • Workflows are defined in the .github/workflows [about][workflow syntax]
  • Monitor: [about]
    • By default, the artifacts and log files generated by workflows are retained for 90 days before they are automatically deleted. You can adjust the retention period depending on the type of repository [retention period]
    • GitHub Actions use the Checks API to output statuses, results, and logs for a workflow. GitHub creates a new check suite for each workflow run. The check suite contains a check run for each job in the workflow, and each job includes steps [run logs][cheks api]
    • The logs can be viewed in "Actions" tab. In case a pull request, it can be viewd on the "Checks" tab
    • Workflow badges in a private repository are not accessible externally to prevent embedding or linking from unauthorized sources status badge
    • Adding the parameter "?branch=BRANCH-NAME" to the workflow status badge URL allows you to specify the branch for which you want to display the status.
    • "View workflow file" option in the failed run's menu allow view the workflow file associated with a failed run. [history]
    • Enabling debug logging in the GitHub repository settings increases the verbosity of the job's logs, providing more detailed information that can help troubleshoot issues with the JavaScript action. This is a common first step to gather additional diagnostic information about the failed job. [debug]
    • To enable step debug logging, set the following secret or variable in the repository that contains the workflow: ACTIONS_STEP_DEBUG to true. If both the secret and variable are set, the value of the secret takes precedence over the variable [debug logging]
    • In GitHub Actions, debug messages printed using workflow commands are not displayed in the logs by default. They are only shown when debug logging is explicitly enabled for the workflow run. If debug logging is not enabled, the debug messages will not appear in the logs, even though they were printed successfully. You must create a secret named ACTIONS_STEP_DEBUG with the value true to see the debug messages set by this command in the log. [enabling debug][workflow command]
    • The 'write' access level on a GitHub repository allows users to make changes to the repository, including deleting log files from workflow runs. [run logs]
  • Migrate to GH Actions [migration]
  • Billing and limits [admin]
  • Metrics [metrics]
  • Schedule
    • You can schedule a workflow to run at specific UTC times using POSIX cron syntax. So using the 'on: schedule: cron' then the correct expression, you can customize your workflow to run on weekdays only. [schedule]
    • GitHub allows you to run scheduled workflows once every five minutes. [schedule]
  • continue-on-error allows the workflow to continue even if the step fails [job contibue error]
  • You can delete a workflow run that has been completed or is more than two weeks old. [deleting workflow run]



Actions

  • In GitHub Actions, workflow files are stored in the .github/workflows directory within the code repository [create workflow]
  • The outputs key in the action's metadata syntax is used to declare the outputs produced by the action. These outputs can then be consumed by subsequent steps in the workflow [action metadata syntax]
  • GitHub issues scoped installation tokens to runners that have read access to the repository containing the actions and automatically expire after one hour, ensuring access control and security [sharing actions]
  • Print a debug message to the log: `echo "::debug::message"` [debug msg]
  • The full SHA value must be used when use the commit's SHA for release management [release actions]
  • A composite action allows for consolidating multiple workflow steps into a single action [composite]
  • Semantic versioning (SemVer) provides a systematic approach to versioning (MAJOR.MINOR.PATCH) [build action]
  • All actions require a metadata file (action.yml or action.yaml) that defines the inputs, outputs, and runs configuration for the action [action metadata syntax]
  • In GitHub Actions, the exit code of an action determines its success or failure status. A zero exit code indicates success, and a nonzero exit code signifies failure [exit code]
  • Execute commands directly on the runner using the run keyword [adding scripts]
  • Custom actions:
    • For distribute a custom action: provide a clear and concise description of the action's functionality and selecting the most relevant category [building custom action]
    • The "runs" keyword within an action.yml file is used to define the executable command for the action. The "using" keyword within the "runs" section is specifically used to indicate the type of action being executed (JavaScript action, Docker container action, or composite run steps action) [runs]
    • JavaScript actions, composite actions, docker container actions [about]
    • JavaScript
      • JavaScript actions require that the runs statement takes two arguments: 'using' and 'main'[create js action]
      • JavaScript actions in GitHub repositories differ from traditional Node.js projects in their development and distribution processes. They include dependent packages alongside the code and support tagged releases for direct publication to GitHub Marketplace. [javascript actions]
    • Docker
      • The Dockerfile is required for containerized actions, as it specifies the environment and dependencies needed to run the custom action within a container. Containerized actions offer a more isolated and reproducible environment for the action to execute in, making the Dockerfile an essential component for these types of actions. Docker container actions can only be executed on runners with a Linux operating system [custom action][docker support][docker container action]
      • Checking the GitHub Actions logs provides detailed information about the execution of Docker container actions, including any errors encountered during startup or execution, aiding in troubleshooting. [dockerfile support]
      • To access an environment variable corresponding to an input in a Docker container action, you must pass the input using the args keyword in the action metadata file. This ensures that the input is correctly passed to the Docker container environment [action metadata syntax]
      • The URL for the GitHub Container Registry is ghcr.io. [gh container registry]
      • Running jobs in a container: Use jobs.JOB_ID.container to create a container to run any steps in a job that don't already specify a container. [run in a container]
      • Use container has as advantage easy access to actual or simulated external dependencies [service container]
      • Verify the environment variables passed to your Docker container action: use the env command within the Docker container action to display the environment variables [env replacement]
    • Release:
      • Manage action release: use tags, branches or SHA. [action release]
      • When no version is specified (e.g. uses: actions/checkout ) then it means that the latest version of the action will be used by default [finding and customizing]
      • Best practices for release: Create and validate a release on a release branch before creating a tag; Use semantic versioning; release major versions with a beta tag to indicate their status to distinguish between stable releases and those that are still in development or testing phases; introduce a new major version tag for changes that will break existing workflows; move the major version tag to point to the Git ref of the current release [releasing actions]
    • Toolkit



Manage GitHub Actions for the enterprise

  • Actions can be disabled for all organizations or only for a specific one [policy]
  • To access encrypted secrets within actions and workflows for GitHub Actions, developers can utilize the secrets context provided by GitHub Actions. [secrets]
  • Important balance between security (e.g. IP address) and operational efficiency [hosted runners]
  • Syntax to reference a secret: `secrets.secret_name` [secrets]
  • Workflow templates ensure automation is reused and maintained in your enterprise (public and private repositories of the organization) [create workflow]
  • Organization-template workflow has as benefits: promotes consistency, best practices and saves time [create workflows]
  • Creating a templated workflow for a organization, the workflow files and associated metadata files must be stored inside a directory named workflow-templates within a repository named .github [workflow for organization]
  • To effectively manage and collaborate on your organization's diverse reusable components in GitHub Actions workflows, enforce a standardized naming convention across all teams. [reuse workflow] [avoiding duplication]
  • Reusable workflows can be in the same repository or a different one. In case to set up multiple reusable workflows in your organization, it might be a good idea to set up a common workflow repository.
  • Sharing actions [sharing actions and workflows]
  • To protect sensitive projects while leveraging custom GitHub Actions, you can allow GitHub Actions workflows in your private repository to access another private repository containing the custom action or reusable workflow. This approach ensures that actions or workflows stored in private repositories can be used within workflows defined in other private repositories owned by the same organization or user, preserving security and privacy [sharing from private]
  • You can choose to disable GitHub Actions for all repositories in your organization or only allow specific repositories. You can also limit the use of public actions and reusable workflows so that people can only use local actions and reusable workflows within your organization. [managing permissions]
  • It's possible to create an organization-level secret and configure a policy to limit access to only the specific repositories that can use it [secrets for organization]
  • Runner groups are used to collect sets of runners and create a security boundary around them. It makes possible to configure which organizations or repositories are permitted to run jobs on those sets of machines [runners group]



References