Skip to content

Improve repository documentation #6

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
staging-devin-ai-integration wants to merge 1 commit into
base: main
Choose a base branch
from
Open

Improve repository documentation #6

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
181 changes: 161 additions & 20 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,18 +1,106 @@
# DEVIN-GITHUB-ACTIONS

A collection of GitHub Actions for integrating with the Devin API.
A collection of GitHub Actions for integrating with the Devin API. This repository provides tools to automate Devin session management, secrets handling, knowledge base operations, and playbook management directly from your GitHub workflows.

## Available Actions
## Table of Contents

- [Overview](#overview)
- [Project Structure](#project-structure)
- [Requirements](#requirements)
- [Installation and Configuration](#installation-and-configuration)
- [Quick Start](#quick-start)
- [Available Actions](#available-actions)
- [Features](#features)
- [Examples](#examples)
- [Contributing](#contributing)
- [Support](#support)
- [License](#license)

## Overview

DEVIN-GITHUB-ACTIONS enables seamless integration between GitHub workflows and the Devin AI assistant. With this action, you can programmatically create Devin sessions to automate code reviews, bug fixes, feature implementations, and other development tasks as part of your CI/CD pipeline.

The action communicates with the Devin API using a shell script that handles authentication, request building, and response parsing. It supports all major Devin API endpoints including session management, secrets, knowledge base, and playbooks.

## Project Structure

```
DEVIN-GITHUB-ACTIONS/
├── README.md # This file - main project documentation
├── devin-action/ # Main GitHub Action directory
│ ├── action.yml # GitHub Action definition and inputs/outputs
│ ├── README.md # Detailed action documentation
│ ├── DEPLOYMENT.md # Deployment and publishing guide
│ ├── scripts/
│ │ └── devin-api.sh # Shell script for Devin API interactions
│ └── examples/
│ └── example-workflow.yml # Example GitHub workflow
```

### Devin API Action
## Requirements

A comprehensive GitHub Action for interacting with the Devin API to create and manage Devin sessions programmatically from your GitHub workflows.
Before using this action, ensure you have the following:

📂 **Location**: [`devin-action/`](./devin-action/)
**GitHub Requirements:**
- A GitHub repository with Actions enabled
- Permission to add secrets to your repository
- A workflow file (`.github/workflows/*.yml`)

📖 **Documentation**: See [devin-action/README.md](./devin-action/README.md) for detailed usage instructions
**Devin Requirements:**
- An active Devin account
- A Devin API key (obtain from [Devin settings](https://app.devin.ai/settings))

🚀 **Quick Start**:
**Runtime Dependencies (automatically available in GitHub Actions runners):**
- `bash` (version 4.0 or higher)
- `curl` (for HTTP requests)
- `jq` (for JSON parsing)

## Installation and Configuration

### Step 1: Obtain Your Devin API Key

1. Log in to your Devin account at [app.devin.ai](https://app.devin.ai)
2. Navigate to Settings
3. Generate or copy your API key

### Step 2: Add the API Key to GitHub Secrets

1. Go to your GitHub repository
2. Navigate to **Settings** > **Secrets and variables** > **Actions**
3. Click **New repository secret**
4. Name: `DEVIN_API_KEY`
5. Value: Paste your Devin API key
6. Click **Add secret**

### Step 3: Create a Workflow File

Create a new file in your repository at `.github/workflows/devin.yml` (or any name ending in `.yml`):

```yaml
name: Devin Integration

on:
workflow_dispatch:
inputs:
task:
description: 'Task for Devin'
required: true

jobs:
run-devin:
runs-on: ubuntu-latest
steps:
- name: Create Devin Session
uses: samfert-codeium/DEVIN-GITHUB-ACTIONS/devin-action@main
with:
action: 'create-session'
api-key: ${{ secrets.DEVIN_API_KEY }}
prompt: ${{ github.event.inputs.task }}
```

## Quick Start

Here's a minimal example to create a Devin session:

```yaml
- name: Create Devin Session
Expand All @@ -24,29 +112,82 @@ A comprehensive GitHub Action for interacting with the Devin API to create and m
prompt: 'Fix the failing unit tests'
title: 'Automated Bug Fix'
tags: 'bug-fix,automated'

- name: Display Session URL
run: echo "Session URL: ${{ steps.create-session.outputs.session-url }}"
```

### Features
## Available Actions

The action supports the following operations:

### Session Management
| Action | Description |
|--------|-------------|
| `create-session` | Create a new Devin session with a task prompt |
| `send-message` | Send a follow-up message to an existing session |
| `get-session` | Retrieve details about a specific session |
| `list-sessions` | List all sessions associated with your API key |
| `upload-files` | Upload files to a session for Devin to access |
| `update-tags` | Update the tags on an existing session |

### Secrets Management
| Action | Description |
|--------|-------------|
| `list-secrets` | List all stored secrets |
| `create-secret` | Create a new secret for use in sessions |
| `delete-secret` | Delete an existing secret |

### Knowledge Management
| Action | Description |
|--------|-------------|
| `list-knowledge` | List all knowledge entries |
| `create-knowledge` | Create a new knowledge entry |
| `update-knowledge` | Update an existing knowledge entry |
| `delete-knowledge` | Delete a knowledge entry |

- **Session Management**: Create sessions, send messages, get status, list sessions
- **File Operations**: Upload files to sessions
- **Tagging**: Update session tags
- **Secrets Management**: Create, list, and delete secrets
- **Knowledge Management**: Manage knowledge base entries
- **Playbooks Management**: Create and manage playbooks
### Playbooks Management
| Action | Description |
|--------|-------------|
| `list-playbooks` | List all playbooks |
| `create-playbook` | Create a new playbook |
| `get-playbook` | Get details of a specific playbook |
| `update-playbook` | Update an existing playbook |
| `delete-playbook` | Delete a playbook |

### Prerequisites
## Features

1. Get a Devin API key from your [Devin settings page](https://app.devin.ai/settings)
2. Store it as a GitHub secret (recommended name: `DEVIN_API_KEY`)
**Session Management:** Create and manage Devin sessions programmatically. Start automated code reviews, bug fixes, or feature implementations directly from your CI/CD pipeline.

### Examples
**File Operations:** Upload files to sessions so Devin can access test results, logs, configuration files, or any other resources needed for the task.

See [devin-action/examples/](./devin-action/examples/) for complete workflow examples.
**Tagging System:** Organize sessions with tags for easy filtering and categorization. Update tags as sessions progress through different stages.

**Secrets Management:** Securely store and manage credentials that Devin can use during sessions, such as API keys, database passwords, or service tokens.

**Knowledge Base:** Create and maintain a knowledge base that Devin can reference. Store documentation, coding guidelines, architecture decisions, or any information relevant to your projects.

**Playbooks:** Define reusable workflows and instructions that Devin can follow for specific types of tasks, ensuring consistent approaches across similar problems.

## Examples

See the [examples directory](./devin-action/examples/) for complete workflow examples, including:

- **Basic Session Creation:** Simple workflow to create a Devin session
- **PR Review Automation:** Automatically trigger Devin to review pull requests
- **Scheduled Tasks:** Run Devin sessions on a schedule for maintenance tasks

For detailed usage instructions and all available inputs/outputs, see the [devin-action README](./devin-action/README.md).

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request.
Contributions are welcome! Please feel free to submit a Pull Request. When contributing:

1. Fork the repository
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request

## Support

Expand Down
49 changes: 41 additions & 8 deletions devin-action/examples/example-workflow.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,30 +1,61 @@
# =============================================================================
# Example Devin Workflow
# =============================================================================
# This workflow demonstrates how to use the Devin API GitHub Action to create
# and interact with Devin sessions from your CI/CD pipeline.
#
# PREREQUISITES:
# 1. A Devin API key stored as a GitHub secret named DEVIN_API_KEY
# 2. GitHub Actions enabled on your repository
#
# USAGE:
# 1. Go to the "Actions" tab in your GitHub repository
# 2. Select "Example Devin Workflow" from the left sidebar
# 3. Click "Run workflow"
# 4. Enter a task description and click "Run workflow"
#
# The workflow will create a Devin session with your task and display
# the session URL where you can monitor Devin's progress.
# =============================================================================

name: Example Devin Workflow

# Trigger: Manual workflow dispatch with custom input
# This allows you to run the workflow on-demand from the GitHub UI
on:
workflow_dispatch:
inputs:
task:
# The task description that will be sent to Devin as the prompt
description: 'Task for Devin to perform'
required: true
default: 'Review the codebase and suggest improvements'

jobs:
run-devin:
# Use the latest Ubuntu runner provided by GitHub
runs-on: ubuntu-latest

steps:
# Step 1: Checkout the repository code
# This makes the repository files available to subsequent steps
- name: Checkout code
uses: actions/checkout@v4

# Step 2: Create a new Devin session
# This step calls the Devin API to create a session with the specified task
- name: Create Devin Session
uses: samfert-codeium/DEVIN-GITHUB-ACTIONS/devin-action@main
id: devin-session
id: devin-session # ID used to reference outputs in later steps
with:
action: 'create-session'
api-key: ${{ secrets.DEVIN_API_KEY }}
prompt: ${{ github.event.inputs.task }}
title: 'GitHub Actions Session - ${{ github.run_number }}'
tags: 'github-actions,automated'
action: 'create-session' # The API action to perform
api-key: ${{ secrets.DEVIN_API_KEY }} # API key from repository secrets
prompt: ${{ github.event.inputs.task }} # Task from workflow input
title: 'GitHub Actions Session - ${{ github.run_number }}' # Unique title with run number
tags: 'github-actions,automated' # Tags for categorization

# Step 3: Display session information
# Outputs the session details to the workflow logs for easy access
- name: Display Session Information
run: |
echo "Devin session created successfully!"
Expand All @@ -33,10 +64,12 @@ jobs:
echo ""
echo "You can monitor the session at the URL above."

# Step 4: Send additional context to the session
# Demonstrates how to send follow-up messages to an existing session
- name: Send Additional Context
uses: samfert-codeium/DEVIN-GITHUB-ACTIONS/devin-action@main
with:
action: 'send-message'
action: 'send-message' # Send a message to existing session
api-key: ${{ secrets.DEVIN_API_KEY }}
session-id: ${{ steps.devin-session.outputs.session-id }}
session-id: ${{ steps.devin-session.outputs.session-id }} # Reference the session created above
message: 'This session was triggered from GitHub Actions workflow run ${{ github.run_number }}'
Loading