Skip to content

Commit

Permalink
Merge remote-tracking branch 'docs-public/main' into pipeline-rules
Browse files Browse the repository at this point in the history
  • Loading branch information
gilesgas committed Aug 30, 2024
2 parents 2c6282c + ac97236 commit 443c430
Show file tree
Hide file tree
Showing 38 changed files with 882 additions and 351 deletions.
4 changes: 3 additions & 1 deletion .buildkite/ecr-scan-results-ignore.yml
Original file line number Diff line number Diff line change
Expand Up @@ -18,4 +18,6 @@ ignores:
- id: CVE-2024-0567 # gnutls28 3.7.9-2+deb12u1
- id: CVE-2023-50387 # systemd 252.17-1~deb12u1
- id: CVE-2024-0553 # gnutls28 3.7.9-2
- id: CVE-2024-0567 # gnutls28 3.7.9-2+deb12u1
- id: CVE-2024-0567 # gnutls28 3.7.9-2+deb12u1
- id: CVE-2024-37371 # krb5 1.20.1-2+deb12u1
- id: CVE-2024-37370 # krb5 1.20.1-2+deb12u1
13 changes: 5 additions & 8 deletions CODEOWNERS
Original file line number Diff line number Diff line change
@@ -1,10 +1,7 @@
@dannymidnight

pages/ @mbelton-buildkite @gilesgas
data/ @mbelton-buildkite @gilesgas
images/ @mbelton-buildkite @gilesgas
vale/ @mbelton-buildkite @gilesgas
styleguide/ @mbelton-buildkite @gilesgas

app/assets/ @buildkite/growth-activate
app/views/ @buildkite/growth-activate
pages/ @gilesgas
data/ @gilesgas
images/ @gilesgas
vale/ @gilesgas
styleguide/ @gilesgas
256 changes: 256 additions & 0 deletions CONTRIBUTING.md

Large diffs are not rendered by default.

93 changes: 9 additions & 84 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,10 +1,10 @@
# Buildkite Documentation [![Build status](https://badge.buildkite.com/b1b9e3ef9d893c087f5e5c0a2d04c258ba393bed2379273f63.svg?branch=main)](https://buildkite.com/buildkite/docs)

The source files for the [Buildkite Documentation](https://buildkite.com/docs).
The source files for the [Buildkite Documentation](https://buildkite.com/docs), aka the Buildkite Docs, or just docs.

To contribute, please send a pull request! :heart:

## Development
## Local docs development environment

### Before you start

Expand Down Expand Up @@ -38,7 +38,7 @@ git submodule update --init

### Run the development server

After completing the relevant 'Before you start' steps above:
After completing all the relevant [Before you start](#before-you-start) steps above:

1. Build and run your local Buildkite Docs development server environment.

Expand Down Expand Up @@ -74,92 +74,17 @@ After completing the relevant 'Before you start' steps above:
> [!NOTE]
> If you ever make more significant changes than just page updates (for example, adding a new page), you may need to stop and restart the Buildkite Docs development server to see these changes.
## Updating `buildkite-agent` CLI docs
Learn how to contribute to the Buildkite Docs in the [CONTRIBUTING guide](./CONTRIBUTING.md).

With the development dependencies installed you can update the CLI docs with the following:
## Contributing to the docs and style guides

```bash
# Set a custom PATH to select a locally built buildkite-agent
PATH="$HOME/Projects/buildkite/agent:$PATH" ./scripts/update-agent-help.sh
```

## Updating GraphQL API docs

GraphQL API documentation is generated from a local version of the [Buildkite GraphQL API schema](./data/graphql/schema.graphql).

This repository is kept up-to-date with production based on a [daily scheduled build](https://buildkite.com/buildkite/docs-graphql). The build fetches the latest GraphQL schema, generates the documentation, and publishes a pull request for review.

If you need to fetch the latest schema you can either:

- Manually trigger a build on [`buildkite/docs-graphql`](https://buildkite.com/buildkite/docs-graphql); or
- Run the following in your local environment:

```sh
# Fetch latest schema
API_ACCESS_TOKEN=xxx bundle exec rake graphql:fetch_schema >| data/graphql/schema.graphql

# Generate docs based on latest schema
bundle exec rake graphql:generate
```

## Linting

We spell-check the docs (US English) and run a few automated checks for repeated words, common errors, and markdown and filename inconsistencies.

You can run most of these checks with `./scripts/vale.sh`.

If you've added a new valid word that showing up as a spelling error, add it to `./vale/styles/vocab.txt`.

## Style guides

Our documentation is based on the principles of common sense, clarity, and brevity.

The [writing](/styleguides/writing-style.md) and [Markdown syntax](/styleguides/markdown-syntax-style.md) style guides should provide you a general idea and an insight into our language and writing style, as well as the Markdown syntax we use (including custom formatting elements).
The Buildkite Docs is based on the principles of common sense, clarity, and brevity.

## Search index
Refer to the:

**Note:** By default, search (through Algolia) references the production search index.

The search index is updated once a day by a scheduled build using the config in `config/algolia.json`.

To test changes to the indexing configuration:

1. Make sure you have an API key in `.env` like:

```env
APPLICATION_ID=APP_ID
API_KEY=YOUR_API_KEY
```
2. Run `bundle exec rake update_test_index`.
## Updating the navigation
The navigation is split into the following files:
- `nav_graphql.yml`: For the GraphQL API content.
- `nav.yml`: For everything else.
A combined navigation is generated when the application starts.
Otherwise, to update the general navigation:
1. Edit `nav.yml` with your changes.
1. Restart the application.
## Content keywords
We render content keywords in `data-content-keywords` in the `body` tag to highlight the focus keywords of each page with content authors.
This helps the content team to quickly inspect to see the types of content we're providing across different channels.
Keywords are added as [Frontmatter](https://rubygems.org/gems/front_matter_parser) meta data using the `keywords` key, e.g.:
```md
keywords: docs, tutorial, pipelines, 2fa
```
- [Contributing to the Buildkite Docs](CONTRIBUTING.md) guide for details on how to start making a contribution in a new pull request.

If no keywords are provided it falls back to comma-separated URL path segments.
- [Writing](/styleguides/writing-style.md) and [Markdown syntax](/styleguides/markdown-syntax-style.md) style guides, which should provide a general idea and an insight into the language and writing style used throughout the Buildkite Docs, as well as the Markdown syntax used (including custom formatting elements).

## License

Expand Down
2 changes: 1 addition & 1 deletion config/initializers/content_security_policy.rb
Original file line number Diff line number Diff line change
Expand Up @@ -69,7 +69,7 @@
)

# Specify URI for violation reports
policy.report_uri "https://buildkite.report-uri.com/r/d/csp/reportOnly"
policy.report_uri "https://buildkite.uriports.com/reports/report"
end

# We use nonce for inline scripts
Expand Down
4 changes: 2 additions & 2 deletions data/content/agent_attributes.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -226,13 +226,13 @@ attributes:
default_value: "false"
required: false
desc: |
Do not execute any local hooks, or plugins from any source.
Don't allow any local hooks, or plugins from any source.
- name: no-plugins
env_var: BUILDKITE_NO_PLUGINS
default_value: "false"
required: false
desc: |
Do not load any plugins.
Don't allow loading of plugins.
- name: no-plugin-validation
env_var: BUILDKITE_NO_PLUGIN_VALIDATION
default_value: "true"
Expand Down
35 changes: 25 additions & 10 deletions data/graphql/schema.graphql
Original file line number Diff line number Diff line change
Expand Up @@ -85,6 +85,7 @@ enum APIAccessTokenScopes {
READ_PIPELINES
READ_PIPELINE_TEMPLATES
READ_REGISTRIES
READ_RULES
READ_SUITES
READ_TEAMS
READ_TEST_PLAN
Expand All @@ -99,6 +100,7 @@ enum APIAccessTokenScopes {
WRITE_PIPELINES
WRITE_PIPELINE_TEMPLATES
WRITE_REGISTRIES
WRITE_RULES
WRITE_SUITES
WRITE_TEAMS
WRITE_TEST_PLAN
Expand Down Expand Up @@ -890,6 +892,8 @@ enum AuditEventType {
REGISTRY_TOKEN_DELETED
REGISTRY_TOKEN_UPDATED
REGISTRY_UPDATED
RULE_CREATED
RULE_DELETED
SCM_PIPELINE_SETTINGS_CREATED
SCM_PIPELINE_SETTINGS_DELETED
SCM_PIPELINE_SETTINGS_UPDATED
Expand Down Expand Up @@ -987,7 +991,7 @@ type AuditSubject {
"""
Kinds of subjects which can have audit events performed on them
"""
union AuditSubjectNode = APIAccessToken | AgentToken | AuthorizationBitbucket | AuthorizationGitHub | AuthorizationGitHubEnterprise | Cluster | ClusterPermission | ClusterQueue | ClusterQueueToken | ClusterToken | Email | JobTypeBlock | JobTypeCommand | JobTypeTrigger | JobTypeWait | NotificationServiceSlack | NotificationServiceWebhook | Organization | OrganizationBanner | OrganizationImpersonationRequest | OrganizationInvitation | OrganizationMember | Pipeline | PipelineSchedule | PipelineTemplate | Registry | RegistryToken | SCMPipelineSettings | SCMRepositoryHost | SCMService | SSOProviderGitHubApp | SSOProviderGoogleGSuite | SSOProviderSAML | Secret | Subscription | Suite | TOTP | Team | TeamMember | TeamPipeline | TeamRegistry | TeamSuite | User
union AuditSubjectNode = APIAccessToken | AgentToken | AuthorizationBitbucket | AuthorizationGitHub | AuthorizationGitHubEnterprise | Cluster | ClusterPermission | ClusterQueue | ClusterQueueToken | ClusterToken | Email | JobTypeBlock | JobTypeCommand | JobTypeTrigger | JobTypeWait | NotificationServiceSlack | NotificationServiceWebhook | Organization | OrganizationBanner | OrganizationImpersonationRequest | OrganizationInvitation | OrganizationMember | Pipeline | PipelineSchedule | PipelineTemplate | Registry | RegistryToken | Rule | SCMPipelineSettings | SCMRepositoryHost | SCMService | SSOProviderGitHubApp | SSOProviderGoogleGSuite | SSOProviderSAML | Secret | Subscription | Suite | TOTP | Team | TeamMember | TeamPipeline | TeamRegistry | TeamSuite | User

"""
All the possible types of subjects in an Audit Event
Expand All @@ -1013,6 +1017,7 @@ enum AuditSubjectType {
PIPELINE_TEMPLATE
REGISTRY
REGISTRY_TOKEN
RULE
SCM_PIPELINE_SETTINGS
SCM_REPOSITORY_HOST
SCM_SERVICE
Expand Down Expand Up @@ -8958,11 +8963,6 @@ type Rule implements Node {
"""
effect: RuleEffect
id: ID!

"""
Name of the rule
"""
name: String!
organization: Organization

"""
Expand All @@ -8984,14 +8984,29 @@ type Rule implements Node {
Target type for the rule
"""
targetType: RuleTargetType

"""
The type of rule
"""
type: String!

"""
The public UUID for the rule
"""
uuid: ID!
}

"""
The action a rule enforces
"""
enum RuleAction {
"""
Trigger a build in the target pipeline
Artifacts read
"""
ARTIFACTS_READ

"""
Trigger build
"""
TRIGGER_BUILD
}
Expand All @@ -9010,12 +9025,12 @@ input RuleCreateInput {
A unique identifier for the client performing the mutation.
"""
clientMutationId: String
organizationId: ID!

"""
Rule name
Rule type
"""
name: String!
organizationId: ID!
type: String!

"""
Serialised JSON of the attributes for this rule
Expand Down
9 changes: 9 additions & 0 deletions data/nav.yml
Original file line number Diff line number Diff line change
Expand Up @@ -407,6 +407,8 @@
children:
- name: "Configuring test suites"
path: "test-analytics/test-suites"
- name: "Configuring test splitting"
path: "test-analytics/test-splitting"
- name: "Permissions"
path: "test-analytics/permissions"
- name: "CI environment variables"
Expand Down Expand Up @@ -493,6 +495,13 @@
path: "packages/debian"
- name: "Files"
path: "packages/files"
- name: "Helm"
start_expanded: true
children:
- name: "OCI-based"
path: "packages/helm-oci"
- name: "Standard"
path: "packages/helm"
- name: "Java"
start_expanded: true
children:
Expand Down
2 changes: 1 addition & 1 deletion pages/apis/graphql/schemas/enum/apiaccesstokenscopes.md

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

Loading

0 comments on commit 443c430

Please sign in to comment.