CI/CD Integration

This page is under construction.

Integrating codebrief with CI/CD

Automating context generation within your Continuous Integration/Continuous Deployment (CI/CD) pipeline ensures that your project documentation and context are always up-to-date. This is invaluable for generating context for pull requests, nightly builds, or release artifacts.

This tutorial will guide you through setting up a GitHub Actions workflow to run codebrief automatically.

Why Integrate with CI/CD?

• Automated Context for Pull Requests: Automatically generate and attach context to PRs, making code reviews faster and more efficient.
• Always-Current Documentation: Keep a "live" version of your project's context available for your team.
• Release Artifacts: Bundle a complete project context with every release, providing a snapshot for future reference or for your users.
• Consistency: Ensure that context is always generated with the same configuration and commands, eliminating manual errors.

Prerequisites

• A project hosted on GitHub.
• codebrief installed and configured in your project (with pyproject.toml and a poetry.lock file).
• Basic knowledge of GitHub Actions.

Step 1: Create a GitHub Actions Workflow File

First, create a new workflow file in your repository at .github/workflows/codebrief.yml.

# .github/workflows/codebrief.yml
name: codebrief CI

on:
  push:
    branches:
      - main
  pull_request:
    branches:
      - main

jobs:
  build_context:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v3

      - name: Set up Python
        uses: actions/setup-python@v4
        with:
          python-version: '3.11' # Match your project's Python version

      - name: Install Poetry
        uses: snok/install-poetry@v1

      - name: Install dependencies
        run: poetry install

      - name: Run codebrief
        run: |
          mkdir -p context-artifacts
          poetry run codebrief tree --output context-artifacts/project-tree.txt
          poetry run codebrief flatten . --output context-artifacts/flattened-code.md
          poetry run codebrief deps --output context-artifacts/dependencies.md

      - name: Upload Artifacts
        uses: actions/upload-artifact@v3
        with:
          name: context-artifacts
          path: context-artifacts/

Step 2: Understanding the Workflow

Let's break down what this workflow does:

1. on: This defines when the workflow will run. In this case, it triggers on every push and pull_request to the main branch.

2. jobs: This section defines the jobs to be run. We have one job, build_context.

3. steps: These are the individual actions within the job:

   • Checkout code: Checks out your repository's code so the workflow can access it.
   • Set up Python: Installs the specified version of Python.
   • Install Poetry: Installs Poetry, which is used to manage your project's dependencies.
   • Install dependencies: Installs the project dependencies using poetry install.
   • Run codebrief: This is the core step. It creates a directory called context-artifacts and then runs the tree, flatten, and deps commands, saving the output to that directory.
   • Upload Artifacts: This step takes the files generated by codebrief and uploads them as artifacts. These can then be downloaded from the workflow's summary page.

Step 3: Committing and Running the Workflow

1. Commit the .github/workflows/codebrief.yml file to your repository.
2. Push the changes to GitHub.

Now, every time you push to main or open a pull request, the workflow will run, and you will find the generated context files in the "Artifacts" section of the workflow summary.

Advanced Usage: Context for Pull Requests

You can take this a step further by posting the context as a comment on the pull request. This requires a more advanced workflow using a GitHub App or a personal access token.

Here's an example of how you could modify the workflow to comment on a PR:

# ... (previous steps) ...

      - name: Create PR Comment
        if: github.event_name == 'pull_request'
        uses: actions/github-script@v6
        with:
          github-token: ${{ secrets.GITHUB_TOKEN }}
          script: |
            const fs = require('fs');
            const tree = fs.readFileSync('context-artifacts/project-tree.txt', 'utf8');
            const code = fs.readFileSync('context-artifacts/flattened-code.md', 'utf8');

            const body = `
            ## 🤖 codebrief Analysis

            <details>
            <summary>Project Tree</summary>

            \`\`\`
            ${tree}
            \`\`\`

            </details>

            <details>
            <summary>Flattened Code</summary>

            \`\`\`markdown
            ${code}
            \`\`\`

            </details>
            `;

            github.rest.issues.createComment({
              issue_number: context.issue.number,
              owner: context.repo.owner,
              repo: context.repo.repo,
              body: body
            });

This script uses the actions/github-script action to post a comment with the generated context directly to the pull request, making it incredibly easy for reviewers to get up to speed.

By integrating codebrief into your CI/CD pipeline, you can ensure that valuable project context is always at your fingertips, improving collaboration and efficiency across your team.