https://github.com/endbug/project-fields
:octocat: A GitHub Action to interact with project fields
https://github.com/endbug/project-fields
Last synced: about 1 year ago
JSON representation
:octocat: A GitHub Action to interact with project fields
- Host: GitHub
- URL: https://github.com/endbug/project-fields
- Owner: EndBug
- License: mit
- Created: 2023-05-09T10:11:25.000Z (almost 3 years ago)
- Default Branch: main
- Last Pushed: 2025-02-19T22:32:44.000Z (about 1 year ago)
- Last Synced: 2025-04-23T13:18:47.239Z (about 1 year ago)
- Language: TypeScript
- Homepage:
- Size: 816 KB
- Stars: 8
- Watchers: 1
- Forks: 5
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Funding: .github/FUNDING.yml
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
Awesome Lists containing this project
README
# Project Fields
A GitHub actions to get and set GitHub project fields.
## Table of Contents
- [Inputs](#inputs)
- [Outputs](#outputs)
- [FAQ](#faq)
- [Supported field types](#supported-field-types)
- [Tokens](#tokens)
- [Examples](#examples)
- [Contributors](#contributors-)
- [License](#license)
## Inputs
Here's the complete list of inputs for this action, also available in the [action.yml](action.yml) file.
For a minimal/typical usage, check out the [examples](#examples) section.
```yml
- uses: EndBug/project-fields@v2
with:
# ⬇️ Required inputs ⬇️
# The type of field operation. Valid options are "get", "set", "clear"
operation: get
# A comma-separated list of fields to get or set
# See the FAQ section for a list of supported field types
fields: text,number,date,select
# The GitHub token to use for authentication
# This token should have write access to the project, and read access
# to the issue/PR you're referencing (see the FAQ section for more info)
github_token: ${{ secrets.PROJECT_PAT }}
# The URL of the project
project_url: https://github.com/users/OWNER/projects/123
# ⬇️ Optional inputs ⬇️
# The URL of the issue/PR to reference
# Default: the issue/PR that triggered the workflow run
resource_url: https://github.com/OWNER/REPO/issues/123
# A comma-separated list of values to update the fields with
# The list must have the same length as the fields one, since they have to match up
# Default: ''
values: abc,123,2000-10-30,option
```
## Outputs
The action provides only one output:
- `values`: a comma-separated list of the current values of the fields
## FAQ
### Supported field types
The action supports the following field data types:
| Field Type | GraphQL Type | Description |
| :-----------: | :--------------: | :------------------------------------------------: |
| Text | [String][String] | The literal string in the field |
| Number | [Float][Float] | The string representation of a number |
| Date | [Date][Date] | The date in the YYYY-MM-DD format |
| Single Select | [String][String] | The name of the option (must be an exact match) |
| Iteration | [String][String] | The name of the iteration (must be an exact match) |
[String]: https://docs.github.com/en/graphql/reference/scalars#string
[Float]: https://docs.github.com/en/graphql/reference/scalars#float
[Date]: https://docs.github.com/en/graphql/reference/scalars#date
### Tokens
Your token **has to be a classic PAT**: the new fine-grained tokens do not work with the GraphQL API yet.
The token should have the following scopes:
- `repo`: needed read issues and PRs from private repositories. If you're using the action on a public repository, you can just use `public_repo` instead.
- `project`: needed to update project fields. If you're only using the action to get the fields, you can just use `read:project` instead.
## Examples
### Get field values
```yml
on: [issues, pull_request]
# ...
- uses: EndBug/project-fields@v2
id: fields
with:
operation: get
fields: text,number,date,select
github_token: ${{ secrets.PROJECT_PAT }}
project_url: https://github.com/OWNER/REPO/issues/123
- run: echo ${{ steps.fields.outputs.values }}
```
### Update field values
```yml
on: [issues, pull_request]
# ...
- name: Set outputs A and B
id: script
run: # ...
- uses: EndBug/project-fields@v2
with:
operation: set
fields: first,second
github_token: ${{ secrets.PROJECT_PAT }}
project_url: https://github.com/OWNER/REPO/issues/123
values: ${{ steps.script.outputs.a }},${{ steps.script.outputs.b }}
```
### Clear fields
```yml
on: [issues, pull_request]
# ...
- uses: EndBug/project-fields@v2
with:
operation: clear
fields: first,second
github_token: ${{ secrets.PROJECT_PAT }}
project_url: https://github.com/OWNER/REPO/issues/123
```
## Contributors ✨
Thanks goes to these wonderful people ([emoji key](https://allcontributors.org/docs/en/emoji-key)):
Federico Grandi
💻
Ben
💻
Nicolas Yarosz
🚧
Kyle Swartz
💻
Add your contributions
This project follows the [all-contributors](https://github.com/all-contributors/all-contributors) specification. Contributions of any kind welcome!
### Additional credits
This project has started thanks to the input of the
GitHub Campus Experts Program 🚩
## License
This project is distributed under the MIT License, check the [license file](LICENSE) for more info.