[2023-01-20] Auto-add workflow for Projects (#33834)

Co-authored-by: github-actions <github-actions@github.com>
Co-authored-by: Sarita Iyer <66540150+saritai@users.noreply.github.com>

Author: 3 people

Diff for: assets/images/help/projects-v2/workflow-autoadd-filter.png

@@ -0,0 +1,58 @@
+---
+title: Adding items automatically
+intro: "You can configure your project to automatically add items from a repository that match a filter."
+miniTocMaxHeadingLevel: 3
+versions:
+  feature: projects-v2-auto-add
+type: tutorial
+product: "The auto-add workflow is available as a beta release for projects owned by organizations using {% data variables.product.prodname_ghe_cloud %}."
+topics:
+  - Projects
+---
+
+## About automatically adding items
+
+You can configure your project's built-in workflows to automatically add new items as they are created or updated in a repository. You can define a filter to only add items that meet your criteria.
+
+When you enable the auto-add workflow, existing items matching your criteria will not be added. The workflow will add items when created or updated if the item matches your filter. For more information on manually adding items, see "[Bulk adding issues and pull requests](/issues/planning-and-tracking-with-projects/managing-items-in-your-project/adding-items-to-your-project#bulk-adding-issues-and-pull-requests)."
+
+The auto-add workflow supports a subset of filters. You can use the following filters when configuring your workflow.
+
+| Qualifier | Possible values
+| --- | --- | --- |
+| `is` | open, closed, merged, draft, issue, pr
+| `label` | "label name"
+| `reason` | completed, reopened, "not planned"
+| `assignee` | {% data variables.product.product_name %} username
+| `no` | label, assignee, reason
+
+All filters, other than `no`, support negation. For example, you could use `-label:bug` to add issues that do not have the "bug" label.
+
+## Configuring the auto-add workflow in your project
+
+{% data reusables.projects.access-workflows %}
+1. In the "Default workflows" list, click **Auto-add to project**.
+   
+   ![Screenshot showing auto-add workflow](/assets/images/help/projects-v2/workflow-autoadd.png)
+   
+1. To start editing the workflow, in the top right, click **Edit**.
+   
+   ![Screenshot showing edit button](/assets/images/help/projects-v2/workflow-start-editing.png)
+   
+1. Under "Filters", select the repository you want to add items from.
+   
+   ![Screenshot showing repository select](/assets/images/help/projects-v2/workflow-autoadd-repo.png)
+   
+1. Next to the repository selection, type the filter criteria you want items to match before they are automatically added to your project.
+   
+   ![Screenshot showing repository select](/assets/images/help/projects-v2/workflow-autoadd-filter.png)
+   
+1. To enable the new workflow, click **Save and turn on workflow**.
+   
+   ![Screenshot showing autoadd workflows](/assets/images/help/projects-v2/workflow-save-and-turn-on.png)
+   
+
+## Further reading
+
+* "[Archiving items from your project](/issues/planning-and-tracking-with-projects/managing-items-in-your-project/archiving-items-from-your-project)"
+* "[Using the built-in automations](/issues/planning-and-tracking-with-projects/automating-your-project/using-the-built-in-automations)"

Diff for: assets/images/help/projects-v2/workflow-autoadd-repo.png

@@ -11,7 +11,7 @@ children:
   - /using-the-built-in-automations
   - /using-the-api-to-manage-projects
   - /automating-projects-using-actions
+  - /adding-items-automatically
   - /archiving-items-automatically
 allowTitleToDifferFromFilename: true
 ---
-

Diff for: assets/images/help/projects-v2/workflow-autoadd.png

@@ -16,7 +16,11 @@ topics:
 
 {% endnote %}
 
-{% data reusables.projects.about-workflows %}
+{% data variables.product.prodname_projects_v2 %} includes built-in workflows that you can use to update the **Status** of items based on certain events. For example, you can automatically set the status to **Todo** when an item is added to your project or set the status to **Done** when an issue is closed.
+
+When your project initializes, two workflows are enabled by default: When issues or pull requests in your project are closed, their status is set to **Done**, and when pull requests in your project are merged, their status is set to **Done**.
+
+{% ifversion projects-v2-auto-archive %}You can also configure {% ifversion projects-v2-auto-add %}workflows{% else %}a workflow{% endif %} to automatically archive items when they meet set criteria{% ifversion projects-v2-auto-add %} and to automatically add items from a repository when they match a filter{% endif %}. For more information, see "[Archiving items automatically](/issues/planning-and-tracking-with-projects/automating-your-project/archiving-items-automatically){% ifversion projects-v2-auto-add %}" and "[Adding items automatically](/issues/planning-and-tracking-with-projects/automating-your-project/adding-items-automatically){% endif %}."{% endif %}
 
 You can enable or disable the built-in workflows for your project.
 

Diff for: assets/images/help/projects-v2/workflow-save-and-turn-on.png

@@ -30,6 +30,12 @@ You can use custom fields to add metadata to your issues, pull requests, and dra
 - A text field to add a quick note.
 - An iteration field to plan work week-by-week, including support for breaks.
 
+### Automating your projects
+
+There are a number of ways you can add automation to your project. Built-in workflows allow you to automatically set fields when items are added or changed{% ifversion projects-v2-auto-archive %}, and you can also configure your project to automatically archive items when they meet certain criteria{% ifversion projects-v2-auto-add %} and automatically add items from a repository when they match set criteria{% endif %}{% endif %}. For more information, see "[Using the built-in automations](/issues/planning-and-tracking-with-projects/automating-your-project/using-the-built-in-automations)."
+
+You can also use the GraphQL API and {% data variables.product.prodname_actions %} to take even greater control of your project. For more information, see "[Using the API to manage Projects](/issues/planning-and-tracking-with-projects/automating-your-project/using-the-api-to-manage-projects)" and "[Automating Projects using Actions](/issues/planning-and-tracking-with-projects/automating-your-project/automating-projects-using-actions)."
+
 {% ifversion projects-v2-tasklists %}
 
 ### Exploring the relationships between issues

Diff for: assets/images/help/projects-v2/workflow-start-editing.png

@@ -62,12 +62,13 @@ To prevent information from getting out of sync, maintain a single source of tru
 
 You can automate tasks to spend less time on busy work and more time on the project itself. The less you need to remember to do manually, the more likely your project will stay up to date.
 
-{% data variables.product.prodname_projects_v2 %} offers built-in workflows. For example, when an issue is closed, you can automatically set the status to "Done." {% ifversion projects-v2-auto-archive %}You can also configure built-in workflows to automatically archive items when they meet certain criteria.{% endif %}
+{% data variables.product.prodname_projects_v2 %} offers built-in workflows. For example, when an issue is closed, you can automatically set the status to "Done." {% ifversion projects-v2-auto-archive %}You can also configure built-in workflows to automatically archive items when they meet certain criteria{% ifversion projects-v2-auto-add %} and to automatically add items from a repository when they match a filter{% endif %}.{% endif %}
 
 Additionally, {% data variables.product.prodname_actions %} and the GraphQL API enable you to automate routine project management tasks. For example, to keep track of pull requests awaiting review, you can create a workflow that adds a pull request to a project and sets the status to "needs review"; this process can be automatically triggered when a pull request is marked as "ready for review."
 
 - For more information about the built-in workflows, see "[Using the built-in automations](/issues/planning-and-tracking-with-projects/automating-your-project/using-the-built-in-automations)."{% ifversion projects-v2-auto-archive %}
-- For more information about automatically archiving items, see "[Archiving items automatically](/issues/planning-and-tracking-with-projects/automating-your-project/archiving-items-automatically)."{% endif %}
+- For more information about automatically archiving items, see "[Archiving items automatically](/issues/planning-and-tracking-with-projects/automating-your-project/archiving-items-automatically)."{% endif %}{% ifversion projects-v2-auto-add %}
+- For more information about automatically archiving items, see "[Adding items automatically](/issues/planning-and-tracking-with-projects/automating-your-project/adding-items-automatically)."{% endif %}
 - For an example workflow, see "[Automating {% data variables.product.prodname_projects_v2 %} using Actions](/issues/planning-and-tracking-with-projects/automating-your-project/automating-projects-using-actions)."
 - For more information about the API, see "[Using the API to manage {% data variables.product.prodname_projects_v2 %}](/issues/planning-and-tracking-with-projects/automating-your-project/using-the-api-to-manage-projects)."
 - For more information about {% data variables.product.prodname_actions %}, see ["{% data variables.product.prodname_actions %}](/actions)."

Diff for: content/issues/planning-and-tracking-with-projects/automating-your-project/adding-items-automatically.md

@@ -14,7 +14,7 @@ topics:
 
 ## Introduction
 
-This guide demonstrates how to use {% data variables.product.prodname_projects_v2 %} to plan and track work. In this guide, you will create a new project and add a custom field to track priorities for your tasks. You'll also learn how to create saved views that help you communicate priorities and progress with your collaborators.
+This guide demonstrates how to use {% data variables.product.prodname_projects_v2 %} to plan and track work. In this guide, you will create a new project and add a custom field to track priorities for your tasks. You'll learn how to create saved views that help you communicate priorities and progress with your collaborators. You'll also set up built-in workflows to manage the items in your project.
 
 ## Prerequisites
 
@@ -146,6 +146,33 @@ To indicate the purpose of the view, give it a descriptive name.
 
 ## Configure built-in automation
 
+{% ifversion projects-v2-auto-add %}
+
+Next, configure the auto-add workflow to automatically add issues opened in a repository with a specific label to your project. 
+
+{% data reusables.projects.access-workflows %}
+1. In the "Default workflows" list, click **Auto-add to project**.
+   
+   ![Screenshot showing auto-add workflow](/assets/images/help/projects-v2/workflow-autoadd.png)
+   
+1. To start editing the workflow, in the top right, click **Edit**.
+   
+   ![Screenshot showing edit button](/assets/images/help/projects-v2/workflow-start-editing.png)
+   
+1. Under "Filters", select the repository you want to add items from.
+   
+   ![Screenshot showing repository select](/assets/images/help/projects-v2/workflow-autoadd-repo.png)
+   
+1. Next to the repository selection, type the filter criteria you want items to match before they are automatically added to your project. For example, to catch all issues and PRs opened with the label "bug", use `is:issue,pr label:bug`.
+   
+   ![Screenshot showing repository select](/assets/images/help/projects-v2/workflow-autoadd-filter.png)
+   
+1. To enable the new workflow, click **Save and turn on workflow**.
+   
+   ![Screenshot showing autoadd workflows](/assets/images/help/projects-v2/workflow-save-and-turn-on.png)
+
+{% endif %}
+
 Finally, add a built in workflow to set the status to **Todo** when an item is added to your project.
 
 1. In the top-right, click {% octicon "kebab-horizontal" aria-label="The menu icon" %} to open the menu.

Diff for: content/issues/planning-and-tracking-with-projects/automating-your-project/index.md

@@ -21,6 +21,8 @@ Your project can track draft issues, issues, and pull requests.
 
 ### Adding issues and pull requests to a project
 
+You can add issues and pull requests to your project individually{% ifversion projects-v2-auto-add %}, automatically, {% endif %} or in bulk. You can also add draft issues which can later be transformed into issues. For more information, see "[Creating draft issues](#creating-draft-issues)."
+
 {% ifversion projects-v2-timeline-events %}
 
 {% note %} 
@@ -33,12 +35,24 @@ When you add an issue or pull request to your project, an event will be added to
 
 {% endif %}
 
+{% ifversion projects-v2-auto-add %}
+
+#### Automatically adding issues and pull requests
+
+You can configure a built-in workflow to automatically add issues and pull requests from a repository when they meet specific filter criteria. For more information about configuring a workflow, see "[Adding items automatically](/issues/planning-and-tracking-with-projects/automating-your-project/adding-items-automatically)."
+
+{% endif %}
+
 #### Pasting the URL of an issue or pull request
 
+You can copy the URL of an issue or pull request into your clipboard and paste that into your project.
+
 {% data reusables.projects.add-item-via-paste %}
 
 #### Searching for an issue or pull request
 
+If you know the issue or pull request number or if you know part of the title, you can search for an issue or pull request directly from your project.
+
 {% data reusables.projects.add-item-bottom-row %}
 2. Enter <kbd>#</kbd>.
 3. Select the repository where the pull request or issue is located. You can type part of the repository name to narrow down your options.
@@ -48,6 +62,8 @@ When you add an issue or pull request to your project, an event will be added to
 
 #### Bulk adding issues and pull requests
 
+You can add multiple issues and pull requests from your project and use filters, such as `label:bug`, to narrow down your search.
+
 1. In the bottom row of the project, click {% octicon "plus" aria-label="plus icon" %}.
   ![Screenshot showing + button at the bottom of the project](/assets/images/help/projects-v2/omnibar-add.png)
 1. Click **Add item from repository**.
@@ -56,6 +72,8 @@ When you add an issue or pull request to your project, an event will be added to
 
 #### Adding multiple issues or pull requests from a repository
 
+You can also add issues and pull requests to your project from a repository's issue and pull request lists.
+
 1. On {% data variables.location.product_location %}, navigate to the repository that contains the issues or pull requests you want to add to your project.
 {% data reusables.repositories.sidebar-issue-pr %}
 1. To the left of each issue title, select the issues that you want to add to your project.
@@ -69,6 +87,8 @@ When you add an issue or pull request to your project, an event will be added to
 
 #### Assigning a project from within an issue or pull request
 
+You can also add an issue or pull request to your project from within the issue or pull request itself.
+
 1. Navigate to the issue or pull request that you want to add to a project.
 2. In the side bar, click **Projects**.
   ![Screenshot showing "Projects" in the issue sidebar](/assets/images/help/projects-v2/issue-sidebar-projects.png)
@@ -79,6 +99,8 @@ When you add an issue or pull request to your project, an event will be added to
 
 #### Using the command palette to add an issue or pull request
 
+You can use the command palette when viewing your project to quickly add items.
+
 1. {% data reusables.projects.open-command-palette %}
 1. Start typing "Add items" and press <kbd>Return</kbd>.
 {% data reusables.projects.bulk-add %}

Diff for: content/issues/planning-and-tracking-with-projects/automating-your-project/using-the-built-in-automations.md

@@ -0,0 +1,4 @@
+# Issue 8996
+# ProjectV2 auto-adding
+versions:
+  ghec: '*'