This repository serves as the organization baseline for OnFrontiers development standards and also provides a local Node.js application for creating and managing Jira tickets across multiple repositories.
- Global Rules: See GLOBAL_RULES.md for organization-wide development standards, tool integration, and repository structure conventions
- Bootstrap Script: Run
bash scripts/bootstrap-global-rules.shto set up team member environment and verify project configurations - For New Projects: Reference the Global Rules in your project's
CLAUDE.mdto inherit organization standards
A local Node.js application for creating and managing tickets across multiple OnFrontiers repositories (Engineering, Product Development, Operations Hub) using the Jira REST API.
- View ticket details
- Update ticket summary and description
- Add comments to tickets
- Search tickets using JQL
- Change ticket status/transitions
- Assign tickets to users
- Create tickets across multiple project spaces (Engineering, Product Development, Operations Hub)
- Automatic space-appropriate defaults and labels
- Interactive command-line interface
-
Install dependencies:
npm install
-
Configure environment variables:
- Copy
.env.exampleto.env - Fill in your Jira credentials:
JIRA_BASE_URL=https://your-domain.atlassian.net JIRA_EMAIL=your-email@example.com JIRA_API_TOKEN=your-api-token
- Copy
-
Get your Jira API token:
- Go to Atlassian Account Settings
- Click "Create API token"
- Copy the generated token to your
.envfile
If you're setting up this repository from GitHub for the first time:
-
Install Git (if not already installed):
- Download from https://git-scm.com/downloads
- Follow the installation wizard
-
Set up SSH keys for GitHub (recommended):
# Generate a new SSH key ssh-keygen -t ed25519_onfrontiers -C "your-email@example.com" # Start the SSH agent eval "$(ssh-agent -s)" # Add your SSH key to the agent ssh-add ~/.ssh/id_ed25519_onfrontiers # Copy the public key to add to GitHub cat ~/.ssh/id_ed25519_onfrontiers.pub
- Go to GitHub.com → Settings → SSH and GPG keys
- Click "New SSH key"
- Paste the public key and save
-
Clone the repository:
git clone git@github.com:onfrontiers/devops-agent.git cd devops-agent -
Install dependencies:
npm install
-
Set up environment:
cp .env.example .env # Edit .env with your Jira credentials (see Setup section above)
Start the application:
npm startOr for development with auto-reload:
npm run devThis tool uses Jira's REST API v3 with basic authentication:
- Username: Your Atlassian email address
- Password: Your API token (not your actual password)
- The
.envfile is gitignored to prevent accidentally committing credentials - Never share your API token or commit it to version control
Create tickets across three main project spaces:
- Engineering: Technical implementation tickets
- Product Development: Product strategy and roadmap tickets
- Operations Hub: Infrastructure, DevOps, and operational improvements
Tickets are automatically configured based on selected space:
- Labels: Applied automatically (e.g., "product-development" for Product Development space)
- Templates: Agnostic templates work across all spaces
- Stages: Defaults to "Definition" stage, with option to specify
- Assignment: No default assignee - always confirmed with user
node src/create[TicketType].js- Create tickets with space-appropriate defaultsnode src/myTickets.js- View your assigned tickets across all spaces
Templates are stored in /templates/ directory:
story-template.json- Based on ENG-4657 structure (Background, Acceptance Criteria, Technical Design)bug-template.json- Bug reporting template (Description, Environment, Sample Record, Steps to reproduce, Intended Result)
- Story/Epic/Task: Background → Acceptance Criteria → Technical Design
- Bug: Description of the bug → Environment questions → Sample Record → Steps to reproduce → Intended Result
When creating tickets, the tool will prompt you to select one or more Jira components for the target project and ask for confirmation.
Interactive
- You will see a numbered list of available components and can select multiple by entering comma-separated numbers.
- A confirmation step shows your selection and requires Y/N to proceed.
Non-interactive and CI
- Provide components by name using one of:
- --components "Name1,Name2"
- COMPONENTS="Name1,Name2" (environment variable)
- To skip components explicitly, use:
- --no-components
- NO_COMPONENTS=1
- If running in a non-interactive (non-TTY) environment without explicit components or --no-components, the script will fail with a helpful message.
Affected commands/scripts
- Menu: npm start → option "Create cost-optimization ticket"
- node src/jira/product-dev/createProductDevelopmentTicket.js
- node src/jira/product-dev/createTestProductTicket.js
- node src/jira/tickets/createAuthStory.js
- node src/jira/tickets/createServiceAccountTicket.js
- node src/jira/tickets/createSearchImprovementEpic.js
Templates
- templates/epic-template.json now includes "components": [] and "fixVersions": []
- story and bug templates already include "components" and "fixVersions"
Examples
- node src/jira/product-dev/createProductDevelopmentTicket.js --components "Search,Operations Hub"
- COMPONENTS="Search,Operations Hub" node src/jira/tickets/createAuthStory.js
- node src/jira/tickets/createServiceAccountTicket.js --no-components
assignee = currentUser()- Your assigned ticketsstatus = "In Progress"- All in-progress ticketsproject = "PROJ" AND status = Open- Open tickets in specific projectcreated >= -7d- Tickets created in the last 7 daysproject = ENG AND (labels IS EMPTY OR labels NOT IN ("cost-reduction", "product-development"))- All Engineering ticketslabels = "product-development"- All Product Development ticketsproject = ENG AND labels = cost-reduction- All Operations Hub tickets (legacy cost-reduction label)
-
Create an Internal Integration:
- https://www.notion.so/profile/integrations
- Click “New integration”, give it a name (e.g., enio-devops-agent), copy the Integration Secret.
-
Define the integration’s scope (what content it can access):
- In the integration UI, select the teamspaces/pages to grant access, OR
- Open a Teamspace “Home” page → Share → add your integration → if available, enable “also share with subpages” to cascade.
-
Configure environment variables:
- In
.env:NOTION_API_KEY=your-integration-secret # Optional convenience if you plan to create pages under a known parent: # NOTION_PARENT_PAGE_ID=d61c8553-007d-4489-a7c3-f1d7af090e05
- In
-
Verify access with curl:
- Replace
<pageId>with a page ID you have access to (e.g., a Teamspace Home page ID).
# Read page metadata curl -sS -H "Authorization: Bearer $NOTION_API_KEY" -H "Notion-Version: 2022-06-28" \ https://api.notion.com/v1/pages/<pageId> # Read page blocks (content) curl -sS -H "Authorization: Bearer $NOTION_API_KEY" -H "Notion-Version: 2022-06-28" \ "https://api.notion.com/v1/blocks/<pageId>/children?page_size=10" # Create a child page under a parent page curl -sS -X POST -H "Authorization: Bearer $NOTION_API_KEY" -H "Notion-Version: 2022-06-28" -H "Content-Type: application/json" \ https://api.notion.com/v1/pages \ -d '{ "parent": { "page_id": "<pageId>" }, "properties": { "title": [{ "text": { "content": "DevOps Agent Access Test" } }] }, "children": [ { "object": "block", "type": "paragraph", "paragraph": { "rich_text": [{ "type": "text", "text": { "content": "Hello from the API." } }] }} ] }'
- Replace
Notes:
- Only
NOTION_API_KEYis required. Scopes are managed in Notion’s integration UI. - Never commit secrets to version control.
- Node.js helpers available:
src/notion/pages/updatePageTitle.jscan programatically update any accessible page title. - Example usage:
node src/notion/examples/updatePageTitle.js "page-id" "New Title"