[comment]: # (This presentation was made with markdown-slides) [comment]: # (Can be found here: https://gitlab.com/da_doomer/markdown-slides) [comment]: # (Compile this presentation with the command below) [comment]: # (mdslides slides.md) [comment]: # (Set the theme:) [comment]: # (markdown: { smartypants: true }) ## Continuous Integration and Continuous Delivery (CI/CD) with GitHub Workflows <br/> ### Andres Rios Tascon Software Engineering Summer School 2024

## What is CI and CD - Continuous Integration:<br> Frequent merging of changes into main branch - Continuous Deployment:<br> Automatic release of new software versions

## What is CI for? - Running tests (dynamic and static) - Check if new changes break any existing functionality - Check if code follows formatting guidelines

## What is CI for? - Building documentation<br> - Run Doxygen/Sphinx/etc generate documentation in pdf or html form - Check if examples in the documentation work

## What is CI for? - Build static websites - Build and publish a website to GitHub Pages/ReadTheDocs/etc

## What is CI for? - Generating pull requests for updates and other maintenance - Update dependencies - Fix typos and coding style

## What is CI for? - Whatever your project needs!

## What are the benefits? - Consistent, controlled environment between runs - Runs every PR/commit/tag/whatever you choose - Can't be skipped or forgotten, no contributor setup - Can run lots of OS's, Python versions, compilers, etc

## Some major CI services - **Travis CI**: Very popular for years, but not anymore. - **Jenkins**: A self-host only OSS solution. - **Appveyor**: The original Windows CI service. - **Circle CI**: The first more “modern” design. - **GitLab CI**: For years, this was one of the best services. Still very good. - **Azure Pipelines**: Very modular design is easy to upgrade and maintain. - **GitHub Actions (GHA)**: Extremely simple and popular. Actions are easy to write and share.

### Today we will be focusing on GitHub Actions <br> We first need to briefly discuss exit codes and YAML.

### Exit codes - Every time you run a command in a shell there is an exit code that indicates if it ran successfully, or if there was an error. - An exit code of `0` indicates that the command ran successfully, other numbers indicate an error. - Sometimes different numbers correspond to different errors.

### Exit codes ```bash [1-3|4-7|8-12] > mkdir test > echo $? 0 > mkdir test mkdir: test: File exists > echo $? 1 > mkdir -z test mkdir: illegal option -- z usage: mkdir [-pv] [-m mode] directory_name ... > echo $? 64 ```

### Exit codes - CI workflows will typically stop once they encounter a non-zero exit code. - Sometimes you may need to run a command that might fail, but you want the workflow to proceed. - Some scripts and binaries don't respect this standard and return non-zero exit codes even when successful.

### Exit codes Error codes can be ignored using logical or (||) ```bash > mkdir -z test || echo "ignore" ignore ``` It is also useful to use logical and (&&) to run a command only if another one is successful. ``` > <command1> && <command2> ```

### YAML YAML (YAML Ain’t Markup Language, originally Yet Another Markup Language) is a human-readable data serialization language. - Easy to read and use - Very commonly used in CI configuration files. - File extension is .yml or .yaml

### YAML Defining scalar values: ```yaml number-value: 42 boolean-value: true # can also be on or yes string-value: "Hello world" another-string: String without quotes ```

### YAML Defining lists: ```yaml colors: - red - green - blue more_colors: [black, white] ```

### YAML Defining dictionaries: ```yaml person: name: John Smith age: 33 occupation: accountant same_person: {name: John Smith, age: 33, occupation: accountant} ```

### YAML Defining multi-line strings: ```yaml some-text: > Multiple lines of text same-text: "Multiple lines of text\n" ```

### YAML Defining multi-line strings: ```yaml some-text: | Multiple lines of text same-text: "Multiple\nlines\nof\ntext\n" ```

### Setting up GitHub workflows - Each workflow is configured by a yaml file placed in `.github/workflows` - Can be set to trigger by a wide variety of events - Can run your own commands or use actions written by you or third-parties

### Setting up GitHub workflows This is the basic structure of a workflow file. ```yaml on: <event or list of events> jobs: job_1: name: <name of job> runs-on: <type of machine> steps: - run: <command1> - name: <name of step> run: <command 2> job_2: name: <name of job> runs-on: <type of machine> steps: - uses: <some third-party action> ```

### CI/CD hands-on workshop Go to the following link: https://github.com/ariostas-talks/2024-07-31-cicd

### Exercise Create a new workflow that generates these slides and publishes them to GitHub pages. Things you need: - `actions/checkout` - `actions/setup-python` - `markdown-slides` from https://gitlab.com/da_doomer/markdown-slides - `actions/upload-pages-artifact` - `actions/deploy-pages` - Repo > Settings > Pages > Source > GitHub Actions

### Exercise Start by checking out the repo. ```yaml - name: Check out repo uses: actions/checkout@v4 ```

### Exercise Then set up Python. ```yaml - name: Set up Python uses: actions/setup-python@v4 with: python-version: "3.11" ```

### Exercise Install `markdown-slides`. ```yaml - name: Install markdown slides run: pip install git+https://gitlab.com/da_doomer/markdown-slides.git ```

### Exercise Generate the slides. ```yaml - name: Generate slides run: mdslides slides.md --output_dir slides ```

### Exercise Upload pages artifact ```yaml - name: Upload pages artifact uses: actions/upload-pages-artifact@v3 with: path: ./slides ```

### Exercise Deploy to GitHub Pages ```yaml deploy: environment: name: github-pages url: ${{ steps.deployment.outputs.page_url }} runs-on: ubuntu-latest needs: build steps: - name: Deploy to GitHub Pages id: deployment uses: actions/deploy-pages@v3 ```

There's many more things to learn, but with this basic knowledge there is lots of things you can do!