Workflows Configuration

Workflow configuration file use YAML syntax, and must be stored in your repository under .fasterci/config.yaml name. The file must define a single object called workflows consisting a list of workflows configured like this:

workflows:
  - name: bazel CI
  # Define bazel CI workflow here
  - name: gitops
  # Define gitops workflow here

workflows item fields

Key	Required	Type	Description
name	Y	String	Name of the workflow
image	N	String	Docker image to run the workflow
on	Y	Map	Use on to define which events can cause the workflow to run. See on section below
env	N	Map	Map of environment variables in "NAME" : "VALUE" format
secrets	N	Array	List of secrets to mount as environment variables. Secrets should be defined using secrets UI
hide_from_github	N	Boolean	Do not report the result of this workflow to GitHub check.
steps	Y	Array	List of steps to execute. See steps section below
cleanup	N	String	Optional cleanup step, for example git clean -ffdx
max_parallel	N	Integer	Maximum number of parallel workflow runs

on

Use on to define which events can cause the workflow to run. At least on of push, pull_request keys should be defined. If Both are defined, the workflow run will be triggered if any of conditions match.

Key	Required	Type	Description
push	N	Map	Run the workflow on push to a branch or tag. See push section below
pull_request	N	Map	Run the workflow on pull request See pull_request section below

push

Use push to define a branch masks or tag masks to trigger the workflow run. Masks are doublestar aka globstar: **.

Key	Required	Type	Description
branches	N	Array	List of branch masks
tags	N	Array	List of tag masks
branches-ignore	N	Array	List of branch masks to ignore even if they match branches masks
tags-ignore	N	Array	List of tag masks to ignore even if they match tags masks

Example

workflows:
  - name: bazel CI
    on:
      push:
        branches:
          - 'feature/**'
          - 'release/**'
  - name: gitops
    on:
      push:
        tags:
          - 'release/v*'

pull_request

Use pull_request to define branch mask to trigger the forkflow run on pull request opened or updated.

Key	Required	Type	Description
branches	Y	Array	List of branch masks
paths	N	Array	List of file masks to trigger the workflow run if any of files in the pull request matches the mask
branches-ignore	N	Array	List of branch masks to ignore even if they match branches masks
paths-ignore	N	Array	List of file masks to ignore even if they match paths masks

Example

workflows:
  - name: bazel CI
    on:
      pull_request:
        branches:
          - main

env

A map of environment variables that are available to the steps of the workflow.

Example

env:
  USE_BAZEL_VERSION: "5.1.1" #Tell bazelisk to use specific version of bazel

steps Item

steps is a list of steps to execute sequentially. Each step can run a shell command or define a bazel specific step to run bazel build or test commands. One of run or bazel should be specified. Optionally it is possible to configure a step to report as a separate check in GitHub.

Key	Required	Type	Description
name	N	String	Name of the step. It should be set if github_check is used
working-directory	N	String	directory to run commands. Default is the repository root
github_check	N	Boolean	Report the result of the step as a separate github check. name field should be also defined
github_check_md_file	N	String	After completing the step, report as a separate Github Check, using the content of the file as a report body in md format. The file could be generated as a result of the step execution
run	N	String	Arbitrary command execution; Could be multiline
bazel	N	Map	Bazel step, see bazel section below

Example

    steps:
      # run go vet in go subdirectory and report result as a separate GitHub check
      - name: go vet
        github_check: true
        working-directory: go
        run: go vet ./pkg/...
      - name: bazel build and tests
        bazel:
          build_targets: //...
          test_targets: //...
      # configure ssh credentials for github deploy key, run a `bazel run` command that would execute a gitops step from [rules_gitops] and submit a pull request
      - name: Create gitops PRs
        run: | #multiline command
          mkdir /root/.ssh
          echo "$GIT_RW_DEPLOY_KEY" > /root/.ssh/id_rsa
          chmod 400 /root/.ssh/id_rsa
          ssh-keyscan github.com > ~/.ssh/known_hosts
          git config --global user.email "devops@fasterci.com"
          git config --global user.name "GitopsBot"
          bazel run @com_adobe_rules_gitops//gitops/prer:create_gitops_prs -- \
            --release_branch=main \
            --bazel_cmd=bazel \
            --workspace=$(pwd) \
            --target="//manifests/..." \
            --git_repo=git@github.com:fasterci/fasterci.git \
            --gitops_pr_into=main \
            --branch_name=main \
            --git_commit=$(git rev-parse HEAD) \
            --git_server=github \
            --github_repo_owner=fasterci \
            --github_repo=fasterci \
            --github_access_token=$GITHUB_TOKEN

bazel

bazel step is designed to run bazel builds or tests. Implementation of this step greatly reduce the run time relying on replroducability and cache capabilities of bazel At least one (or both) of build_targets or test_targets should be defined. Additional command line flags could be specified using build_flags and test_flags.

bazel fields

Key	Required	Type	Description
build_targets	N	Array	List of bazel targets to build
test_targets	N	Array	List of bazel targets to test
build_flags	N	Array	Build flags to use in addition to defined in /etc/bazel.bazelrc and .bazelrc
test_flags	N	Array	Test flags to use in addition to defined in /etc/bazel.bazelrc and .bazelrc

Example

    steps:
      - name: bazel test
        bazel:
          build_targets:
            - "//..."
          test_flags: 
            - "--test_tag_filters=-e2e,-examples"
          test_targets: 
            - //... 

Real world examples: rules_nodejs, rules_gitops